@acms-subir/core 0.3.3-next.20260929113209 → 0.3.4

package/cli/mobile-doctor.mjs

@@ -0,0 +1,430 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve, relative, sep } from 'node:path';
+import { CORE, exists, fail, readJson } from './common.mjs';
+import { listApps, readApp, appDir, recipes, KINDS, editorRedirect } from './mobile.mjs';
+import { libraryComponents, registryKeys } from './native-sections.mjs';
+
+// `acms mobile doctor [--dir] [--url] [--offline]`: fast, offline-tolerant
+// checks for the site's Expo apps. Each check is pass | warn | fail with a
+// hint; any fail makes the command exit 1. Network checks warn (never fail)
+// when the site can't be reached, and --offline skips them.
+
+/**
+ * Which @acms-subir/client and /native releases go with a core release line,
+ * and the public API version they speak. Rule: the installed packages'
+ * major.minor must equal the line listed for the site's core major.minor.
+ * Add a row whenever a core minor ships with new mobile packages.
+ */
+export const MOBILE_COMPAT = {
+  '0.3': { client: '0.1', native: '0.1', api: 1 },
+  '0.4': { client: '0.1', native: '0.1', api: 1 },
+};
+const line = (v) => String(v ?? '').match(/^(\d+)\.(\d+)/)?.slice(1, 3).join('.') ?? null;
+export function compatFor(coreVersion) { return MOBILE_COMPAT[line(coreVersion)] ?? null; }
+
+const SKIP_DIRS = new Set(['node_modules', '.expo', 'dist', 'web-build', 'ios', 'android', '.git', '.turbo', 'coverage']);
+const SOURCE = /\.(tsx?|jsx?|mjs|cjs)$/;
+const ADMIN_ROUTES = /['"`](?:https?:\/\/[^'"`\s]*)?\/api\/(agent|ai|backup|design|drafts|email|export|import|live|mcp|media|ops|restore|webhooks)(?:[/?'"`]|$)/;
+const SECRET_KEY = /(TOKEN|SECRET|PASSWORD|PASSWD|PRIVATE|API_?KEY|ACCESS_?KEY)/i;
+const PLACEHOLDER_ID = /^com\.example\.|__ACMS_/;
+
+async function files(root, dir = root, out = []) {
+  for (const e of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+    if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) await files(root, join(dir, e.name), out); }
+    else out.push(relative(root, join(dir, e.name)).split(sep).join('/'));
+  }
+  return out;
+}
+const pkgVersion = async (dir, name) => (await readJson(join(dir, 'node_modules', name, 'package.json')).catch(() => null))?.version ?? null;
+
+function hostKind(url) {
+  let u;
+  try { u = new URL(url); } catch { return 'invalid'; }
+  const h = u.hostname.replace(/^\[|\]$/g, '');
+  if (h === 'localhost' || h === '::1' || /^127\./.test(h) || h === '0.0.0.0') return 'loopback';
+  if (/^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)/.test(h) || /\.(local|lan|internal|ts\.net)$/.test(h) || !h.includes('.')) return 'private';
+  return 'public';
+}
+
+async function getJson(url, timeout = 3000) {
+  try {
+    const r = await fetch(url, { signal: AbortSignal.timeout(timeout), headers: { accept: 'application/json' }, redirect: 'follow' });
+    const text = await r.text();
+    let json = null;
+    try { json = JSON.parse(text); } catch { /* not JSON */ }
+    return { status: r.status, json, type: r.headers.get('content-type') ?? '' };
+  } catch (e) {
+    return { status: 0, error: e?.name === 'TimeoutError' ? 'timed out' : 'unreachable' };
+  }
+}
+
+const envValue = async (dir, file) => (await readFile(join(dir, file), 'utf8').catch(() => '')).match(/^\s*EXPO_PUBLIC_ACMS_URL\s*=\s*(.*)$/m)?.[1]?.trim().replace(/^['"]|['"]$/g, '') || null;
+
+function checker() {
+  const checks = [];
+  const add = (status, id, title, message, extra = {}) => { checks.push({ id, status, title, message, ...extra }); };
+  return { checks, pass: (...a) => add('pass', ...a), warn: (...a) => add('warn', ...a), fail: (...a) => add('fail', ...a) };
+}
+
+async function siteMobileConfig() {
+  const discovered = await readJson(resolve('.astro/acms-project.json')).catch(() => null);
+  return discovered && 'mobile' in discovered ? (discovered.mobile ?? {}) : null;
+}
+
+async function coreVersion() {
+  // The site's installed core decides compatibility; this CLI's own version otherwise.
+  const own = (await readJson(join(CORE, 'package.json'))).version;
+  const site = await readJson(resolve('node_modules/@acms-subir/core/package.json')).catch(() => null);
+  return site?.version ?? own;
+}
+
+/**
+ * Editor apps: the sign-in pieces must line up. The site must have editor
+ * apps on and list this app's return address (<scheme>://auth) exactly; the
+ * app needs secure storage and the system browser module.
+ */
+async function editorChecks(c, { app, deps, hasModules, dir, expo, url, live, ctx }) {
+  // packages that keep the sign-in safe
+  const need = [['expo-secure-store', 'fail', 'tokens are kept in the Keychain / Keystore'], ['expo-web-browser', 'fail', 'sign-in opens the site in the system browser'], ['expo-crypto', 'warn', 'PKCE randomness on devices without Web Crypto']];
+  const lacking = [], lackingSoft = [];
+  for (const [name, level, why] of need) {
+    const declared = !!deps[name];
+    const installed = hasModules ? await exists(join(dir, 'node_modules', name)) : declared;
+    if (!declared || !installed) (level === 'fail' ? lacking : lackingSoft).push(`${name} ${declared ? 'is declared but not installed' : 'is missing'} (${why})`);
+  }
+  const install = `cd ${app.dir} && npx expo install expo-secure-store expo-web-browser expo-crypto`;
+  if (lacking.length) c.fail('editor-storage', 'Secure sign-in', `${[...lacking, ...lackingSoft].join('; ')}.`, { hint: install });
+  else if (lackingSoft.length) c.warn('editor-storage', 'Secure sign-in', `${lackingSoft.join('; ')}.`, { hint: install });
+  else c.pass('editor-storage', 'Secure sign-in', 'expo-secure-store, expo-web-browser and expo-crypto installed.');
+
+  // return address: app scheme ↔ the site's redirectUris
+  const scheme = Array.isArray(expo.scheme) ? expo.scheme[0] : expo.scheme;
+  const redirect = scheme ? editorRedirect(scheme) : null;
+  const config = ctx.mobileConfig?.editor;
+  const snippet = `acms({ mobile: { editor: { redirectUris: ['${redirect ?? '<scheme>://auth'}'] } } })`;
+  let online = null;
+  if (live && url) {
+    const r = await getJson(`${url}/api/v1/admin/me`);
+    online = r.status === 404 ? 'off' : r.status === 401 ? 'on' : null;
+  }
+  if (!redirect) c.fail('editor-redirect', 'Sign-in return address', 'app.json has no "scheme", so the site can\'t send the person back to the app.', { hint: `Set expo.scheme (e.g. your bundle id, lowercase) in ${app.dir}/app.json, then add <scheme>://auth to the site: ${snippet}` });
+  else if (config === undefined || ctx.mobileConfig === null) {
+    if (online === 'off') c.fail('editor-redirect', 'Sign-in return address', `Editor apps are turned off on ${url}.`, { hint: `Add ${snippet} to astro.config.mjs, then restart or deploy the site.` });
+    else c.warn('editor-redirect', 'Sign-in return address', `Couldn't read the site's config to confirm ${redirect} is allowed${online === 'on' ? ' (editor apps are on)' : ''}.`, { hint: 'Run npx astro sync (or start the dev server) so doctor can read .astro/acms-project.json.' });
+  }
+  else if (!config.enabled) c.fail('editor-redirect', 'Sign-in return address', 'Editor apps are not turned on for this site (no mobile.editor.redirectUris).', { hint: `Add ${snippet} to astro.config.mjs, then restart or deploy the site.` });
+  else if (!config.redirectUris.includes(redirect)) c.fail('editor-redirect', 'Sign-in return address', `The site allows ${config.redirectUris.join(', ')}, not this app's ${redirect}.`, { hint: `Add '${redirect}' to mobile.editor.redirectUris in astro.config.mjs (it must match app.json's scheme exactly), then restart or deploy.` });
+  else if (online === 'off') c.fail('editor-redirect', 'Sign-in return address', `astro.config lists ${redirect}, but ${url} has editor apps off.`, { hint: 'Restart the dev server or deploy the site so it picks up the config.' });
+  else {
+    const web = config.redirectUris.filter((u) => /^https?:/.test(u));
+    c.pass('editor-redirect', 'Sign-in return address', `${redirect} is allowed by the site${online === 'on' ? ' (editor API on)' : ''}${web.length ? `; web: ${web.join(', ')}` : '; add an https://…/auth address too if you ship the web build'}.`);
+  }
+}
+
+async function doctorApp(app, flags, ctx) {
+  const dir = resolve(app.dir);
+  const c = checker();
+  const pkg = await readJson(join(dir, 'package.json'));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const hasModules = await exists(join(dir, 'node_modules'));
+  const appJson = await readJson(join(dir, 'app.json')).catch(() => null);
+  const expo = appJson?.expo ?? appJson ?? {};
+
+  // 1. marker
+  const editor = app.kind === 'editor';
+  if (KINDS.includes(app.kind)) c.pass('app', 'App', `${app.kind} app “${app.name}” in ${app.dir}/`);
+  else c.warn('app', 'App', `Unknown app kind “${app.kind}” in ${app.dir}/package.json.`, { hint: 'This version of acms knows "client" and "editor" apps; update @acms-subir/core.' });
+
+  // 2. Expo SDK
+  const expoVersion = hasModules ? await pkgVersion(dir, 'expo') : null;
+  if (!deps.expo) c.fail('expo', 'Expo SDK', 'expo is not a dependency.', { hint: `cd ${app.dir} && npx expo install expo` });
+  else if (!hasModules) c.fail('expo', 'Expo SDK', `Dependencies are not installed (${app.dir}/node_modules is missing).`, { hint: `cd ${app.dir} && npm install` });
+  else if (!expoVersion) c.fail('expo', 'Expo SDK', 'expo is declared but not installed.', { hint: `cd ${app.dir} && npm install` });
+  else {
+    const sdk = expoVersion.split('.')[0];
+    const off = [];
+    for (const name of Object.keys(deps).filter((n) => /^expo-/.test(n))) {
+      const v = await pkgVersion(dir, name);
+      const major = v?.split('.')[0];
+      if (v && Number(major) >= 50 && major !== sdk) off.push(`${name}@${v}`);
+    }
+    if (off.length) c.warn('expo', 'Expo SDK', `SDK ${sdk}, but some Expo packages are from another SDK: ${off.join(', ')}.`, { hint: `cd ${app.dir} && npx expo install --fix` });
+    else c.pass('expo', 'Expo SDK', `SDK ${sdk} (expo ${expoVersion})`);
+  }
+
+  // 3. ACMS packages vs core
+  const compat = compatFor(ctx.core);
+  const versions = {};
+  const problems = [], notes = [];
+  for (const name of ['client', 'native']) {
+    const full = `@acms-subir/${name}`;
+    if (!deps[full]) { problems.push(`${full} is not a dependency`); continue; }
+    const v = hasModules ? await pkgVersion(dir, full) : null;
+    versions[name] = v;
+    if (!hasModules) continue;
+    if (!v) { problems.push(`${full} is declared but not installed`); continue; }
+    if (v === '0.0.0' || v.includes('-')) notes.push(`${full} ${v} is a local or prerelease build`);
+    else if (compat && line(v) !== compat[name]) problems.push(`${full} ${v} does not match core ${ctx.core} (needs ${compat[name]}.x)`);
+  }
+  if (problems.length) c.fail('packages', 'ACMS packages', `${problems.join('; ')}.`, { hint: `cd ${app.dir} && npx expo install @acms-subir/client@~${compat?.client ?? '0'}.0 @acms-subir/native@~${compat?.native ?? '0'}.0` + (hasModules ? '' : ` (or npm install)`) });
+  else if (!hasModules) c.pass('packages', 'ACMS packages', 'Declared (not installed yet; see Expo SDK).');
+  else if (!compat) c.warn('packages', 'ACMS packages', `client ${versions.client}, native ${versions.native}; core ${ctx.core} has no compatibility entry in this CLI.`, { hint: 'Update the site: npx acms update' });
+  else if (notes.length) c.warn('packages', 'ACMS packages', `${notes.join('; ')}; compatibility with core ${ctx.core} can't be checked.`, { hint: `Released versions for core ${line(ctx.core)}.x are ${compat.client}.x.` });
+  else c.pass('packages', 'ACMS packages', `client ${versions.client}, native ${versions.native} match core ${ctx.core}`);
+
+  // 4. site address
+  const prod = await envValue(dir, '.env'), dev = await envValue(dir, '.env.local');
+  const url = (flags.url ?? dev ?? prod ?? '').replace(/\/+$/, '') || null;
+  const urlNotes = [], urlWarn = [];
+  if (!prod && !dev && !flags.url) c.fail('site-url', 'Site address', 'EXPO_PUBLIC_ACMS_URL is not set in .env or .env.local.', { hint: `Add EXPO_PUBLIC_ACMS_URL=https://your-site to ${app.dir}/.env` });
+  else {
+    for (const [label, value] of [['.env', prod], ['.env.local', dev]]) {
+      if (!value) continue;
+      const kind = hostKind(value);
+      if (kind === 'invalid') { urlWarn.push(`${label} has an invalid URL (${value})`); continue; }
+      if (kind === 'loopback') urlWarn.push(`${label} points at ${value}; phones can't reach localhost (simulators and web can)`);
+      else if (label === '.env' && kind === 'private') urlWarn.push(`.env (the address baked into store builds) is a private address (${value})`);
+      if (kind === 'public' && new URL(value).protocol === 'http:') urlWarn.push(`${label} uses http on a public host (${value}); use https`);
+      urlNotes.push(`${label}: ${value}`);
+    }
+    if (!prod) urlWarn.push('.env has no EXPO_PUBLIC_ACMS_URL, so builds have no production address');
+    if (urlWarn.length) c.warn('site-url', 'Site address', `${urlWarn.join('; ')}.`, { hint: 'For a phone: npx acms mobile dev (writes .env.local). For builds: .env = https://your-site.' });
+    else c.pass('site-url', 'Site address', urlNotes.join(', '));
+  }
+
+  // 5. site reachable + API version
+  let site = null;
+  const online = !flags.offline && url && hostKind(url) !== 'invalid';
+  if (flags.offline) c.pass('site', 'Site API', 'Skipped (--offline).');
+  else if (!url || hostKind(url) === 'invalid') c.warn('site', 'Site API', 'No usable site address to check.');
+  else {
+    const r = await getJson(`${url}/api/v1/site`);
+    if (r.status === 200 && r.json?.version === 1 && r.json.data) {
+      site = r.json.data;
+      const want = compat?.api ?? 1;
+      if (site.apiVersion !== want) c.fail('site', 'Site API', `${url} speaks API v${site.apiVersion}; this app's client expects v${want}.`, { hint: 'Update the site and the app packages to matching releases (npx acms update, then npx acms mobile doctor).' });
+      else c.pass('site', 'Site API', `${url} is up (“${site.name}”, API v${site.apiVersion})`);
+    } else if (r.status === 0) c.warn('site', 'Site API', `${url} is ${r.error}.`, { hint: 'Start the site (npx acms mobile dev) or pass --url; --offline skips network checks.' });
+    else c.fail('site', 'Site API', `${url}/api/v1/site returned ${r.status}${r.json ? '' : ' (not the ACMS API)'}.`, { hint: 'Check EXPO_PUBLIC_ACMS_URL points at the site origin and the site runs @acms-subir/core with the mobile API.' });
+  }
+  const live = !!site;
+
+  // 6. app ids
+  if (!appJson) c.fail('app-ids', 'App identity', 'app.json is missing or not valid JSON.', { hint: `Restore ${app.dir}/app.json (see the starter: npx acms add mobile --dry-run).` });
+  else {
+    const ios = expo.ios?.bundleIdentifier, android = expo.android?.package;
+    const issues = [];
+    if (!ios) issues.push('ios.bundleIdentifier is not set');
+    else if (PLACEHOLDER_ID.test(ios)) issues.push(`ios.bundleIdentifier ${ios} is a placeholder`);
+    if (!android) issues.push('android.package is not set');
+    else if (PLACEHOLDER_ID.test(android)) issues.push(`android.package ${android} is a placeholder`);
+    if (!expo.scheme) issues.push('scheme is not set (needed for myapp:// links and auth redirects)');
+    if (issues.length) c.warn('app-ids', 'App identity', `${issues.join('; ')}.`, { hint: `Set real reverse-DNS ids (e.g. org.yoursite.app) in ${app.dir}/app.json before the first store build; they can't change after release.` });
+    else c.pass('app-ids', 'App identity', `iOS ${ios}, Android ${android}, scheme ${expo.scheme}`);
+  }
+
+  // 7. deep links (client apps) / sign-in (editor apps)
+  if (editor) await editorChecks(c, { app, dir, deps, hasModules, expo, url, live, ctx });
+  else if (appJson) {
+    const config = ctx.mobileConfig;
+    const host = (() => { try { return new URL(prod ?? url).hostname; } catch { return null; } })();
+    const issues = [], ok = [];
+    if (config?.ios) {
+      if (config.ios.bundleId !== expo.ios?.bundleIdentifier) issues.push({ s: 'fail', m: `site mobile.ios.bundleId ${config.ios.bundleId} ≠ app.json ios.bundleIdentifier ${expo.ios?.bundleIdentifier ?? '(unset)'}` });
+      if (host && !(expo.ios?.associatedDomains ?? []).includes(`applinks:${host}`)) issues.push({ s: 'warn', m: `app.json ios.associatedDomains lacks "applinks:${host}"` });
+    }
+    if (config?.android) {
+      if (config.android.package !== expo.android?.package) issues.push({ s: 'fail', m: `site mobile.android.package ${config.android.package} ≠ app.json android.package ${expo.android?.package ?? '(unset)'}` });
+      const filters = expo.android?.intentFilters ?? [];
+      if (host && !filters.some((f) => f.autoVerify && (f.data ?? []).some((d) => d.host === host && d.scheme === 'https'))) issues.push({ s: 'warn', m: `app.json android.intentFilters has no autoVerify https filter for ${host}` });
+    }
+    if (live) {
+      const base = url;
+      const [aasa, links] = await Promise.all([getJson(`${base}/.well-known/apple-app-site-association`), getJson(`${base}/.well-known/assetlinks.json`)]);
+      const iosId = expo.ios?.bundleIdentifier, pkgId = expo.android?.package;
+      if (aasa.status === 200) {
+        const ids = (aasa.json?.applinks?.details ?? []).flatMap((d) => d.appID ? [d.appID] : d.appIDs ?? []);
+        if (ids.some((id) => id.endsWith(`.${iosId}`))) ok.push('apple-app-site-association lists this app');
+        else issues.push({ s: 'fail', m: `apple-app-site-association does not list ${iosId} (has ${ids.join(', ') || 'none'})` });
+      } else if (config?.ios) issues.push({ s: 'fail', m: `/.well-known/apple-app-site-association returned ${aasa.status || aasa.error}` });
+      if (links.status === 200) {
+        const pkgs = Array.isArray(links.json) ? links.json.map((s) => s?.target?.package_name).filter(Boolean) : [];
+        if (pkgs.includes(pkgId)) ok.push('assetlinks.json lists this app');
+        else issues.push({ s: 'fail', m: `assetlinks.json does not list ${pkgId} (has ${pkgs.join(', ') || 'none'})` });
+      } else if (config?.android) issues.push({ s: 'fail', m: `/.well-known/assetlinks.json returned ${links.status || links.error}` });
+    }
+    const configured = config?.ios || config?.android || ok.length;
+    const hint = 'Set acms({ mobile: { ios: { teamId, bundleId }, android: { package, sha256CertFingerprints } } }) in astro.config.mjs to match app.json, restart or deploy the site, and add associatedDomains / intentFilters in app.json (acms docs mobile → Deep links).';
+    if (issues.some((i) => i.s === 'fail')) c.fail('deep-links', 'Deep links', `${issues.map((i) => i.m).join('; ')}.`, { hint });
+    else if (issues.length) c.warn('deep-links', 'Deep links', `${issues.map((i) => i.m).join('; ')}.`, { hint });
+    else if (configured) c.pass('deep-links', 'Deep links', ok.length ? ok.join('; ') : `Configured${live ? '' : ' (site files not checked offline)'}.`);
+    else c.pass('deep-links', 'Deep links', `Not configured (optional)${config === null && !live ? '; run astro sync to let doctor read the site config' : ''}.`, { hint: 'To open site links in the app, see acms docs mobile → Deep links.' });
+  }
+
+  // 8. section coverage (client apps render pages; editor apps edit them)
+  const sources = (await files(dir)).filter((f) => SOURCE.test(f) && !f.endsWith('.d.ts'));
+  const texts = new Map(await Promise.all(sources.map(async (f) => [f, await readFile(join(dir, f), 'utf8').catch(() => '')])));
+  if (editor) { /* not applicable */ }
+  else if (!live) c.pass('sections', 'Section coverage', flags.offline ? 'Skipped (--offline).' : 'Skipped (site not reachable).');
+  else {
+    // Home first: its absolute url tells us the site's own origin for menu links.
+    const pageUrl = (slug) => `${url}/api/v1/pages/${slug.split('/').map(encodeURIComponent).join('/')}`;
+    const home = await getJson(pageUrl('home'));
+    let origin = new URL(url).origin;
+    try { if (home.json?.data?.url) origin = new URL(home.json.data.url).origin; } catch { /* keep */ }
+    const slugs = [];
+    for (const item of site.menu ?? []) {
+      try {
+        const u = new URL(item.href, origin);
+        if (u.origin !== origin && u.origin !== new URL(url).origin) continue;
+        const slug = u.pathname.replace(/^\/+|\/+$/g, '');
+        if (slug && slug !== 'home' && !slugs.includes(slug) && slugs.length < 11) slugs.push(slug);
+      } catch { /* not a URL */ }
+    }
+    const pages = [{ slug: 'home', r: home }, ...(await Promise.all(slugs.map(async (slug) => ({ slug, r: await getJson(pageUrl(slug)) }))))];
+    const used = new Map();
+    for (const { slug, r } of pages) if (r.status === 200) for (const s of r.json?.data?.sections ?? []) used.set(s.type, [...(used.get(s.type) ?? []), slug]);
+    const registry = new Set(registryKeys(texts.get('sections/index.ts') ?? '').map((k) => k.split(':')[0]));
+    const library = await libraryComponents();
+    const all = [...texts.values()].join('\n');
+    const fallbackOff = !deps['react-native-webview'] || /webSectionFallback=\{\s*false\s*\}/.test(all);
+    const partlyOff = /webFallback=\{\s*false\s*\}/.test(all);
+    const web = [...used.keys()].filter((t) => !registry.has(t) && !library[t]).sort();
+    const where = (t) => `${t} (${[...new Set(used.get(t))].join(', ')})`;
+    const checked = pages.filter((p) => p.r.status === 200).map((p) => p.slug);
+    if (!web.length) c.pass('sections', 'Section coverage', `All ${used.size} section types on ${checked.join(', ')} render natively.`);
+    else if (fallbackOff) c.warn('sections', 'Section coverage', `No native component and the web view is off${deps['react-native-webview'] ? '' : ' (react-native-webview is not installed)'}: ${web.map(where).join(', ')}. These show as a generic view.`, { hint: 'Write sections/<Type>.tsx and register it in sections/index.ts (acms docs mobile → Common tasks), or turn the web view back on.' });
+    else if (partlyOff) c.warn('sections', 'Section coverage', `Shown as a web view where allowed, generic where webFallback={false}: ${web.map(where).join(', ')}.`, { hint: 'Give these a native component in sections/index.ts.' });
+    else c.pass('sections', 'Section coverage', `Native: ${used.size - web.length} types; web view: ${web.map(where).join(', ')}.`, { hint: 'Give the busiest of these a native component for a native look.' });
+  }
+
+  // 9. content the app asks for by slug (pages, calendars) exists on the site
+  const consts = new Map();
+  for (const t of texts.values()) for (const m of t.matchAll(/\bconst\s+([A-Za-z_$][\w$]*)\s*(?::\s*string\s*)?=\s*['"]([^'"\n]+)['"]/g)) consts.set(m[1], m[2]);
+  const refs = { page: new Map(), calendar: new Map() };
+  const note = (kind, raw, file) => {
+    const slug = /^['"]/.test(raw) ? raw.slice(1, -1) : consts.get(raw);
+    if (slug && !/[${}]/.test(slug)) refs[kind].set(slug, [...new Set([...(refs[kind].get(slug) ?? []), file])]);
+  };
+  for (const [f, t] of texts) {
+    for (const m of t.matchAll(/\busePage\(\s*('[^']*'|"[^"]*"|[A-Za-z_$][\w$]*)/g)) note('page', m[1], f);
+    for (const m of t.matchAll(/<Sections\b[^>]*?\bpage=(?:\{\s*)?('[^']*'|"[^"]*"|[A-Za-z_$][\w$]*)/g)) note('page', m[1], f);
+    for (const m of t.matchAll(/\bcalendar\s*(?::|=\{?)\s*('[^']*'|"[^"]*"|[A-Za-z_$][\w$]*)/g)) note('calendar', m[1], f);
+  }
+  const wanted = refs.page.size + refs.calendar.size;
+  if (!live) c.pass('content', 'Site content', wanted ? `${wanted} page/calendar slug${wanted === 1 ? '' : 's'} not checked (${flags.offline ? '--offline' : 'site not reachable'}).` : 'The app asks for no pages or calendars by slug.');
+  else {
+    const missing = [];
+    for (const [slug, where] of refs.page) {
+      const r = await getJson(`${url}/api/v1/pages/${slug.split('/').map(encodeURIComponent).join('/')}`);
+      if (r.status === 404) missing.push(`page “${slug}” (${where.join(', ')}) is not published`);
+    }
+    if (refs.calendar.size) {
+      const r = await getJson(`${url}/api/v1/calendars`);
+      const known = new Set((r.json?.data?.calendars ?? []).map((cal) => cal.slug));
+      if (r.status === 200) for (const [slug, where] of refs.calendar) if (!known.has(slug)) missing.push(`calendar “${slug}” (${where.join(', ')}) is not a public calendar`);
+    }
+    if (missing.length) c.warn('content', 'Site content', `${missing.join('; ')}.`, { hint: 'The app shows an empty state until the owner creates it in the admin (Pages, Calendar). Tell them what to create; never hardcode it in the app.' });
+    else c.pass('content', 'Site content', wanted ? `Found on the site: ${[...[...refs.page.keys()].map((s) => `page ${s}`), ...[...refs.calendar.keys()].map((s) => `calendar ${s}`)].join(', ')}.` : 'The app asks for no pages or calendars by slug.');
+  }
+
+  // 10. secrets
+  const found = [], soft = [];
+  for (const [f, text] of texts) {
+    const lines = text.split('\n');
+    lines.forEach((l, i) => {
+      const at = `${f}:${i + 1}`;
+      if (/\bACMS_TOKEN\b/.test(l)) found.push(`${at} ACMS_TOKEN`);
+      if (/acms_(?:key|agent)_[A-Za-z0-9]{8,}/.test(l)) found.push(`${at} an ACMS API key`);
+      if (/['"`](?:Authorization['"`]?\s*[:,]\s*['"`])?Bearer\s+[A-Za-z0-9._~+/=-]{12,}/.test(l)) found.push(`${at} a Bearer token literal`);
+      if (ADMIN_ROUTES.test(l)) soft.push(`${at} an admin API route`);
+      if (editor) {
+        if (/AsyncStorage|async-storage/.test(l) && /token|auth|session|credential/i.test(l)) found.push(`${at} tokens in AsyncStorage (use the EditorProvider's secure storage)`);
+        if (/console\.(log|info|debug|warn|error)\s*\(/.test(l) && /(access|refresh)_?token|accessToken|refreshToken|authorization|tokens\b|code_verifier|codeVerifier/i.test(l)) found.push(`${at} logs a token`);
+        if (/secureTextEntry|type=['"]password['"]|autoComplete=['"](current-)?password['"]/.test(l)) found.push(`${at} a password field (staff sign in on the website, never in the app)`);
+      }
+    });
+  }
+  const all = await readdir(dir).catch(() => []);
+  const gitignore = await readFile(join(dir, '.gitignore'), 'utf8').catch(() => null);
+  const ignored = (name) => gitignore != null && gitignore.split(/\r?\n/).map((l) => l.trim()).some((p) => p && !p.startsWith('#') && (p === name || new RegExp(`^${p.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`).test(name)));
+  for (const env of all.filter((n) => /^\.env/.test(n))) {
+    const text = await readFile(join(dir, env), 'utf8').catch(() => '');
+    for (const m of text.matchAll(/^\s*([A-Z0-9_]+)\s*=\s*(.*)$/gm)) {
+      if (!SECRET_KEY.test(m[1]) || !m[2].trim()) continue;
+      if (m[1].startsWith('EXPO_PUBLIC_')) found.push(`${env} ${m[1]} (EXPO_PUBLIC_ values are bundled into the app)`);
+      else if (!ignored(env)) found.push(`${env} ${m[1]} (this file is not git-ignored)`);
+      else soft.push(`${env} ${m[1]} (apps don't need secrets)`);
+    }
+    if (env !== '.env' && env !== '.env.example' && !ignored(env)) soft.push(`${env} is not in .gitignore`);
+  }
+  if (gitignore == null) soft.push('.gitignore is missing');
+  else if (!ignored('.env.local')) soft.push('.gitignore does not ignore .env.local (the dev address)');
+  const hint = editor
+    ? 'Editor apps sign in through the site only: no password fields, tokens only through <EditorProvider> (secure storage), never logged or in AsyncStorage. No API keys: anything in the bundle is readable by anyone.'
+    : 'Remove tokens and keys from the app: it uses the public /api/v1 only, with no credentials. Anything in the bundle is readable by anyone.';
+  if (found.length) c.fail('secrets', 'Secrets', `${found.join('; ')}.`, { hint });
+  else if (soft.length) c.warn('secrets', 'Secrets', `${soft.join('; ')}.`, { hint });
+  else c.pass('secrets', 'Secrets', `No tokens, keys or admin routes in ${sources.length} source files.`);
+
+  // 11. recipes
+  const added = [];
+  for (const r of (await recipes()).filter((x) => x.kind === app.kind)) {
+    let have = 0;
+    for (const f of r.files) if (await exists(join(dir, f))) have++;
+    if (have && have * 2 >= r.files.length) added.push(r);
+  }
+  const missing = [], notes2 = [];
+  for (const r of added) {
+    const lack = r.packages.filter((p) => !deps[p]);
+    if (lack.length) missing.push({ recipe: r.name, packages: lack });
+    else if (hasModules) for (const p of r.packages) if (!(await exists(join(dir, 'node_modules', p)))) missing.push({ recipe: r.name, packages: [p], install: true });
+    if (r.name === 'push') {
+      if (!(expo.plugins ?? []).some((p) => (Array.isArray(p) ? p[0] : p) === 'expo-notifications')) notes2.push('push: add "expo-notifications" to app.json plugins');
+      if (!expo.extra?.eas?.projectId) notes2.push('push: no EAS project id in app.json (extra.eas.projectId), so Expo push tokens fail; run npx eas-cli init in the app folder');
+      // the site side: /api/v1/push/topics exists only when push is on
+      let siteOff = ctx.mobileConfig?.push?.enabled === false;
+      if (live) siteOff = (await getJson(`${url}/api/v1/push/topics`)).status === 404;
+      if (siteOff) notes2.push('push: push notifications are off for the site; set acms({ mobile: { push: true } }) in astro.config.mjs and restart or deploy');
+    }
+  }
+  if (missing.length) c.fail('recipes', 'Recipes', missing.map((m) => `${m.recipe} needs ${m.packages.join(', ')}${m.install ? ' (declared, not installed)' : ''}`).join('; ') + '.', { hint: `cd ${app.dir} && npx expo install ${[...new Set(missing.flatMap((m) => m.packages))].join(' ')}` });
+  else if (notes2.length) c.warn('recipes', 'Recipes', `${notes2.join('; ')}.`);
+  else c.pass('recipes', 'Recipes', added.length ? `${added.map((r) => r.name).join(', ')}: packages installed.` : 'None added.');
+
+  const summary = { pass: 0, warn: 0, fail: 0 };
+  for (const x of c.checks) summary[x.status]++;
+  return { dir: app.dir, kind: app.kind, name: app.name, url, ok: summary.fail === 0, summary, checks: c.checks };
+}
+
+export async function mobileDoctor(flags) {
+  let apps;
+  if (flags.dir) {
+    const app = await readApp(appDir(flags.dir).path);
+    if (!app) fail('NOT_FOUND', `${flags.dir} is not an ACMS mobile app (no "acms" marker in its package.json).`, [], ['acms mobile list']);
+    apps = [app];
+  } else apps = await listApps();
+  if (!apps.length) fail('NOT_FOUND', 'No mobile app found in this site.', [], ['acms add mobile']);
+  if (flags.url) { try { new URL(flags.url); } catch { fail('USAGE', '--url must be your site address, e.g. https://example.com.'); } }
+  const ctx = { core: await coreVersion(), mobileConfig: await siteMobileConfig() };
+  const results = [];
+  for (const app of apps) results.push(await doctorApp(app, flags, ctx));
+  const summary = { pass: 0, warn: 0, fail: 0 };
+  for (const r of results) for (const k of Object.keys(summary)) summary[k] += r.summary[k];
+  return { ok: summary.fail === 0, core: ctx.core, compatibility: compatFor(ctx.core), offline: !!flags.offline, summary, apps: results };
+}
+
+export function renderDoctor(data) {
+  const out = [];
+  for (const app of data.apps) {
+    out.push(`${app.dir}/  ${app.kind} app “${app.name}”`);
+    for (const x of app.checks) {
+      out.push(`  ${x.status === 'pass' ? 'ok  ' : x.status === 'warn' ? 'warn' : 'FAIL'}  ${x.title}: ${x.message}`);
+      if (x.hint && x.status !== 'pass') out.push(`        → ${x.hint}`);
+    }
+    out.push('');
+  }
+  const s = data.summary;
+  out.push(`${s.pass} passed, ${s.warn} warning${s.warn === 1 ? '' : 's'}, ${s.fail} failed${data.offline ? ' (offline)' : ''}`);
+  return out.join('\n');
+}