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

package/cli/mobile.mjs

@@ -0,0 +1,315 @@
+import { readdir, readFile, writeFile, mkdir, appendFile } from 'node:fs/promises';
+import { join, resolve, relative, dirname, isAbsolute, sep } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { networkInterfaces } from 'node:os';
+import { CORE, fail, exists, readJson } from './common.mjs';
+
+// Mobile apps are standalone Expo projects beside the site (default mobile/),
+// never npm workspaces of it. Their package.json carries "acms": {"app": kind}.
+//   add mobile [client|editor] [--dir] [--name] [--bundle] [--url]   copy a blank starter
+//   mobile list | mobile dev [--dir] [--port]                        find / run apps
+//   mobile recipe list | mobile recipe add <name> [--dir]            copy recipe screens
+// Client apps (default dir mobile/) show the site to visitors; editor apps
+// (default dir mobile-editor/) are for staff: sign in through the site, edit.
+
+const TEMPLATES = join(CORE, 'mobile-template');
+const RECIPES = join(TEMPLATES, 'recipes');
+export const KINDS = ['client', 'editor'];
+const DEFAULT_DIR = { client: 'mobile', editor: 'mobile-editor' };
+// npm drops dotfiles from published packages, so the template ships them bare.
+const RENAMES = { gitignore: '.gitignore', 'env.example': '.env.example' };
+const slugify = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 50) || 'my-app';
+const titleCase = (s) => String(s).split(/[-_\s]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
+const BUNDLE = /^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$/;
+
+async function walk(root, base = root) {
+  const out = [];
+  for (const entry of (await readdir(root, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) out.push(...(await walk(path, base)));
+    else out.push(relative(base, path).split(sep).join('/'));
+  }
+  return out;
+}
+const target = (file) => file.split('/').map((p) => RENAMES[p] ?? p).join('/');
+
+export function appDir(dir) {
+  const path = resolve(dir);
+  const rel = relative(process.cwd(), path);
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) fail('USAGE', '--dir must be a folder inside this site, e.g. mobile.');
+  return { path, rel: rel.split(sep).join('/') };
+}
+
+function defaultBundle(url, slug, suffix = 'app') {
+  const host = new URL(url).hostname;
+  const id = (s) => { const v = s.toLowerCase().replace(/[^a-z0-9_]/g, ''); return /^[a-z]/.test(v) ? v : `x${v}`; };
+  if (host === 'localhost' || /^[\d.]+$/.test(host) || host.includes(':') || !host.includes('.')) return { bundle: `com.example.${id(slug)}`, placeholder: true };
+  return { bundle: [...host.replace(/^www\./, '').split('.').reverse().map(id), suffix].join('.'), placeholder: false };
+}
+/** an editor app's URL scheme: its bundle id, lowercased (RFC 8252 §7.1 reverse-DNS scheme) */
+export const editorScheme = (bundle) => bundle.toLowerCase().replace(/_/g, '-');
+export const editorRedirect = (scheme) => `${scheme}://auth`;
+
+const CONFIG_FILES = ['astro.config.mjs', 'astro.config.ts', 'astro.config.js', 'astro.config.mts'];
+const quote = (v) => `'${String(v).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+/**
+ * Add the editor app's return address to acms({ mobile: { editor: { redirectUris } } })
+ * when the config has one of a few unambiguous shapes; otherwise say exactly
+ * what to paste. Never rewrites anything it doesn't fully recognize.
+ */
+export async function editorConfigChange(redirectUri, name) {
+  const snippet = `acms({ mobile: { editor: { name: ${quote(name)}, redirectUris: [${quote(redirectUri)}] } } })`;
+  const file = (await Promise.all(CONFIG_FILES.map(async (f) => ((await exists(f)) ? f : null)))).find(Boolean);
+  if (!file) return { file: 'astro.config.mjs', skipped: `No astro.config found. Add ${snippet} to your acms() options.`, snippet };
+  const text = await readFile(file, 'utf8');
+  if (text.includes(`'${redirectUri}'`) || text.includes(`"${redirectUri}"`)) return { file, already: `${redirectUri} is already listed.`, snippet };
+  const count = (re) => (text.match(re) ?? []).length;
+  const write = (next) => async () => { await writeFile(file, next); };
+  const uri = quote(redirectUri);
+  if (count(/redirectUris\s*:\s*\[/g) === 1) {
+    const next = text.replace(/redirectUris\s*:\s*\[/, (m) => `${m}${uri}, `);
+    return { file, change: `add ${redirectUri} to mobile.editor.redirectUris`, apply: write(next), snippet };
+  }
+  const calls = count(/\bacms\s*\(/g);
+  if (calls === 1 && !/\beditor\s*:/.test(text)) {
+    const entry = `editor: { name: ${quote(name)}, redirectUris: [${uri}] }`;
+    if (/\bacms\s*\(\s*\)/.test(text)) return { file, change: 'turn on editor apps: acms({ mobile: { editor } })', apply: write(text.replace(/\bacms\s*\(\s*\)/, `acms({ mobile: { ${entry} } })`)), snippet };
+    if (count(/\bmobile\s*:\s*\{/g) === 1) return { file, change: 'turn on editor apps (mobile.editor)', apply: write(text.replace(/\bmobile\s*:\s*\{/, (m) => `${m} ${entry},`)), snippet };
+    if (!/\bmobile\s*:/.test(text) && /\bacms\s*\(\s*\{/.test(text)) {
+      // keep the file's layout: a multi-line options object gets its own line
+      const next = text.replace(/\bacms\s*\(\s*\{([ \t]*\r?\n([ \t]*))?/, (m, nl, indent) => (nl ? `${m}mobile: { ${entry} },\n${indent}` : `${m} mobile: { ${entry} },`));
+      return { file, change: 'turn on editor apps: acms({ mobile: { editor } })', apply: write(next), snippet };
+    }
+  }
+  return { file, skipped: `Couldn't safely edit ${file}. Add the return address yourself: ${snippet} (merge into your existing acms options), then restart or deploy the site.`, snippet };
+}
+
+// Keep the site's TypeScript and Docker builds from picking up the app.
+async function siteChanges(rel) {
+  const changes = [];
+  if (await exists('tsconfig.json')) {
+    const text = await readFile('tsconfig.json', 'utf8');
+    let raw;
+    try { raw = JSON.parse(text); } catch { changes.push({ file: 'tsconfig.json', skipped: `Not plain JSON; add "${rel}" to its "exclude" if it includes the whole folder.` }); }
+    if (raw) {
+      const include = Array.isArray(raw.include) ? raw.include : null;
+      const covers = !include || include.some((p) => !/^(\.\/)?(src|\.astro)(\/|$)/.test(p));
+      const excluded = (raw.exclude ?? []).some((p) => p.replace(/^\.\//, '').replace(/\/(\*\*)?$/, '') === rel);
+      if (covers && !excluded) changes.push({ file: 'tsconfig.json', change: `exclude "${rel}"`, apply: async () => { raw.exclude = [...(raw.exclude ?? []), rel]; await writeFile('tsconfig.json', JSON.stringify(raw, null, 2) + '\n'); } });
+    }
+  }
+  if (await exists('.dockerignore')) {
+    const lines = (await readFile('.dockerignore', 'utf8')).split(/\r?\n/).map((l) => l.trim());
+    if (!lines.includes(rel) && !lines.includes(`${rel}/`)) changes.push({ file: '.dockerignore', change: `ignore "${rel}"`, apply: () => appendFile('.dockerignore', `${lines[lines.length - 1] === '' ? '' : '\n'}${rel}\n`) });
+  }
+  return changes;
+}
+const report = (changes) => changes.map(({ apply, ...c }) => c);
+
+export async function addMobile(args, flags) {
+  const kind = args[0] ?? 'client';
+  if (!KINDS.includes(kind)) fail('USAGE', `Unknown app kind “${kind}”.`, [], ['acms add mobile client', 'acms add mobile editor']);
+  if (args.length > 1) fail('USAGE', 'Too many arguments.', [], ['acms add mobile [client|editor] [--dir mobile]']);
+  const editor = kind === 'editor';
+  let pkg;
+  try { pkg = await readJson('package.json'); } catch { fail('NOT_A_PROJECT', "Run from your site's folder (it has a package.json)."); }
+  const { path, rel } = appDir(flags.dir ?? DEFAULT_DIR[kind]);
+  if ((await exists(path)) && (await readdir(path).catch(() => ['?'])).length && !flags.force)
+    fail('EXISTS', `${rel}/ already exists and is not empty; nothing was changed.`, [], ['Pick another folder with --dir, or --force to write the starter over it.']);
+  const siteName = titleCase(pkg.name?.replace(/^@[^/]+\//, '') || 'My App');
+  const name = (flags.name ?? (editor ? `${siteName} Staff` : siteName)).trim();
+  if (!name || name.length > 60) fail('USAGE', '--name must be 1–60 characters.');
+  const url = (flags.url ?? 'http://localhost:4321').replace(/\/+$/, '');
+  let parsed;
+  try { parsed = new URL(url); } catch { fail('USAGE', '--url must be your site address, e.g. https://example.com.'); }
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.search || parsed.hash) fail('USAGE', '--url must be an http(s) site address without credentials, query or fragment.');
+  const slug = slugify(name);
+  const fallback = defaultBundle(url, slug, editor ? 'staff' : 'app');
+  const bundle = flags.bundle ?? fallback.bundle;
+  if (!BUNDLE.test(bundle)) fail('USAGE', `Bundle id “${bundle}” is not valid. Use reverse-DNS letters, digits and underscores, e.g. org.riverside.${editor ? 'staff' : 'app'}.`);
+  // client apps use a short scheme for links; editor apps a reverse-DNS one (it receives sign-in codes)
+  const scheme = editor ? editorScheme(bundle) : slug;
+  const redirectUri = editor ? editorRedirect(scheme) : null;
+  const root = join(TEMPLATES, kind);
+  const files = (await walk(root)).map((f) => ({ from: f, to: target(f) }));
+  const changes = await siteChanges(rel);
+  const config = editor && !flags['no-config'] ? await editorConfigChange(redirectUri, name) : null;
+  if (config?.apply) changes.push(config);
+  const warnings = [
+    ...(!flags.bundle && fallback.placeholder ? [`Bundle id ${bundle} is a placeholder; set a real one in ${rel}/app.json (or --bundle) before your first store build.${editor ? ' The scheme and the site\'s redirectUris must change with it.' : ''}`] : []),
+    ...(!flags.url ? [`The app points at ${url}. Use --url https://your-site or edit ${rel}/.env; npx acms mobile dev sets a phone-reachable address for development.`] : []),
+    ...(config?.skipped ? [config.skipped] : []),
+    ...(editor && flags['no-config'] ? [`The site won't accept sign-ins from this app until you add it: ${config?.snippet ?? `acms({ mobile: { editor: { redirectUris: ['${redirectUri}'] } } })`}`] : []),
+  ];
+  const plan = {
+    kind, dir: rel, name, slug, scheme, bundle, url, ...(editor ? { redirectUri, clientId: bundle, webRedirect: 'https://<where you host the web build>/auth (http://localhost/auth covers local development)' } : {}),
+    files: [...files.map((f) => f.to), '.env'], siteChanges: report(changes), warnings,
+  };
+  if (flags['dry-run']) return { dryRun: true, ...plan };
+  const replacements = { __ACMS_APP_NAME__: name, __ACMS_APP_SLUG__: slug, __ACMS_APP_SCHEME__: scheme, __ACMS_BUNDLE_ID__: bundle, __ACMS_SITE_URL__: url, __ACMS_APP_DIR__: rel, __ACMS_REDIRECT_URI__: redirectUri ?? '' };
+  for (const f of files) {
+    let text = await readFile(join(root, f.from), 'utf8');
+    for (const [k, v] of Object.entries(replacements)) text = text.replaceAll(k, f.from.endsWith('.json') ? JSON.stringify(v).slice(1, -1) : v);
+    await mkdir(dirname(join(path, f.to)), { recursive: true });
+    await writeFile(join(path, f.to), text);
+  }
+  await writeFile(join(path, '.env'), `# Public site address baked into the app. Development overrides go in .env.local.\nEXPO_PUBLIC_ACMS_URL=${url}\n`);
+  for (const c of changes) await c.apply();
+  const next = editor
+    ? [`cd ${rel} && npm install`, ...(config?.apply ? ['Restart or deploy the site so it accepts sign-ins from the app'] : config?.already ? [] : [`Add ${redirectUri} to acms({ mobile: { editor: { redirectUris } } }) in astro.config and restart the site`]), `npx acms mobile dev --dir ${rel}`, 'npx acms mobile recipe list']
+    : [`cd ${rel} && npm install`, 'npx acms mobile dev', 'npx acms mobile recipe list'];
+  return { created: rel, ...plan, next };
+}
+
+// ---- find apps ---------------------------------------------------------------
+
+export async function readApp(dir) {
+  const pkg = await readJson(join(dir, 'package.json')).catch(() => null);
+  if (!pkg?.acms?.app) return null;
+  const app = await readJson(join(dir, 'app.json')).catch(() => ({}));
+  const env = async (f) => (await readFile(join(dir, f), 'utf8').catch(() => '')).match(/^EXPO_PUBLIC_ACMS_URL=(.*)$/m)?.[1]?.trim();
+  return { dir: relative(process.cwd(), dir).split(sep).join('/') || '.', kind: pkg.acms.app, name: app.expo?.name ?? pkg.name, url: await env('.env'), devUrl: await env('.env.local'), installed: await exists(join(dir, 'node_modules')) };
+}
+
+export async function listApps() {
+  const apps = [];
+  const scan = async (dir, depth) => {
+    for (const e of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+      if (!e.isDirectory() || e.name.startsWith('.') || ['node_modules', 'dist', 'src', 'data'].includes(e.name)) continue;
+      const app = await readApp(join(dir, e.name));
+      if (app) apps.push(app); else if (depth > 1) await scan(join(dir, e.name), depth - 1);
+    }
+  };
+  await scan(process.cwd(), 2);
+  return apps;
+}
+
+async function pickApp(dir, kind) {
+  if (dir) {
+    const app = await readApp(appDir(dir).path);
+    if (!app) fail('NOT_FOUND', `${dir} is not an ACMS mobile app (no "acms" marker in its package.json).`, [], ['acms mobile list']);
+    return app;
+  }
+  const apps = await listApps();
+  if (!apps.length) fail('NOT_FOUND', 'No mobile app found in this site.', [], ['acms add mobile']);
+  // with a client and an editor app, a kind (from the recipe) picks the one
+  const matching = kind ? apps.filter((a) => a.kind === kind) : apps;
+  if (matching.length === 1) return matching[0];
+  if (apps.length > 1) fail('USAGE', 'Several mobile apps found; choose one with --dir.', apps.map((a) => `${a.dir} (${a.kind})`));
+  return apps[0];
+}
+
+// ---- dev ---------------------------------------------------------------------
+
+function tailscaleIp() {
+  for (const bin of ['tailscale', '/Applications/Tailscale.app/Contents/MacOS/Tailscale']) {
+    const r = spawnSync(bin, ['ip', '-4'], { encoding: 'utf8', timeout: 3000 });
+    const ip = r.status === 0 ? r.stdout.split(/\s+/).find((x) => /^100\.\d+\.\d+\.\d+$/.test(x)) : undefined;
+    if (ip) return ip;
+  }
+}
+export function phoneAddress() {
+  const ts = tailscaleIp();
+  if (ts) return { ip: ts, via: 'tailscale' };
+  const candidates = Object.entries(networkInterfaces()).flatMap(([name, list]) => (list ?? []).filter((a) => (a.family === 'IPv4' || a.family === 4) && !a.internal && !a.address.startsWith('169.254.')).map((a) => ({ name, ip: a.address })));
+  const privateLan = (ip) => /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(ip);
+  const lan = candidates.find((c) => privateLan(c.ip) && /^(en|eth|wlan|wl)/.test(c.name)) ?? candidates.find((c) => privateLan(c.ip)) ?? candidates[0];
+  if (!lan) fail('NO_NETWORK', 'No network address a phone could reach was found.', [], ['Join Wi-Fi or Tailscale, then try again.']);
+  return { ip: lan.ip, via: 'lan' };
+}
+async function probe(url) {
+  try { const r = await fetch(url, { signal: AbortSignal.timeout(1500) }); await r.body?.cancel(); return true; } catch { return false; }
+}
+
+export async function mobileDev(flags) {
+  const app = await pickApp(flags.dir);
+  const port = Number(flags.port ?? 4321);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) fail('USAGE', '--port must be a port number.');
+  const { ip, via } = phoneAddress();
+  const siteUrl = `http://${ip}:${port}`;
+  const local = async () => (await probe(`http://127.0.0.1:${port}/api/v1/site`)) || probe(`http://[::1]:${port}/api/v1/site`);
+  const [reachable, onLocal] = [await probe(`${siteUrl}/api/v1/site`), await local()];
+  const site = reachable ? 'running' : onLocal ? 'localhost-only' : 'start';
+  const plan = {
+    app: app.dir, address: ip, via, siteUrl, site,
+    steps: [
+      ...(site === 'start' ? [`npx astro dev --host 0.0.0.0 --port ${port}  (log: .acms/mobile-dev-site.log)`] : []),
+      `write ${app.dir}/.env.local: EXPO_PUBLIC_ACMS_URL=${siteUrl}`,
+      `cd ${app.dir} && npx expo start  (REACT_NATIVE_PACKAGER_HOSTNAME=${ip})`,
+    ],
+  };
+  if (flags['dry-run']) return { dryRun: true, ...plan, installed: app.installed };
+  if (site === 'localhost-only') fail('UNREACHABLE', `The site is running on port ${port} but only on localhost, so a phone can't reach it.`, [], [`Restart it with: npx astro dev --host 0.0.0.0 --port ${port}`]);
+  if (!app.installed) fail('NOT_INSTALLED', `Install the app first: cd ${app.dir} && npm install`);
+  if (flags.json) fail('USAGE', 'mobile dev is interactive; use --dry-run --json to see the plan.');
+  let child;
+  if (site === 'start') {
+    await mkdir('.acms', { recursive: true });
+    const { openSync } = await import('node:fs');
+    const log = openSync('.acms/mobile-dev-site.log', 'a');
+    child = spawn('npx', ['astro', 'dev', '--host', '0.0.0.0', '--port', String(port)], { stdio: ['ignore', log, log] });
+    console.error(`Starting the site on ${siteUrl} …`);
+    const until = Date.now() + 120_000;
+    while (!(await local())) {
+      if (child.exitCode !== null || Date.now() > until) { child.kill(); fail('SITE_FAILED', 'The site dev server did not start.', [], ['See .acms/mobile-dev-site.log']); }
+      await new Promise((r) => setTimeout(r, 1000));
+    }
+  }
+  await writeFile(join(app.dir, '.env.local'), `# Written by acms mobile dev: the site as your phone reaches it (${via}).\nEXPO_PUBLIC_ACMS_URL=${siteUrl}\n`);
+  console.error(`Site: ${siteUrl} (${via === 'tailscale' ? 'Tailscale' : 'local network'})`);
+  const code = await new Promise((done) => {
+    const expo = spawn('npx', ['expo', 'start'], { cwd: app.dir, stdio: 'inherit', env: { ...process.env, REACT_NATIVE_PACKAGER_HOSTNAME: ip } });
+    const stop = () => expo.kill('SIGINT');
+    process.once('SIGINT', stop);
+    expo.on('exit', (c) => { process.off('SIGINT', stop); done(c ?? 0); });
+  });
+  child?.kill();
+  return { stopped: true, ...plan, exitCode: code };
+}
+
+// ---- recipes -----------------------------------------------------------------
+
+export async function recipes() {
+  const out = [];
+  for (const name of (await readdir(RECIPES).catch(() => [])).sort()) {
+    const meta = await readJson(join(RECIPES, name, 'recipe.json')).catch(() => null);
+    if (meta) out.push({ name, kind: meta.kind ?? 'client', ...meta, files: (await walk(join(RECIPES, name, 'files'))).map(target) });
+  }
+  return out;
+}
+
+export async function recipeCommand(sub, args, flags) {
+  if (sub === 'list') {
+    const all = await recipes();
+    const apps = await listApps();
+    const kinds = new Set(apps.map((a) => a.kind));
+    return { recipes: kinds.size === 1 ? all.filter((r) => kinds.has(r.kind)) : all, ...(kinds.size === 1 ? { app: apps[0].dir, kind: apps[0].kind } : {}), next: 'acms mobile recipe add <name>' };
+  }
+  if (sub !== 'add') fail('USAGE', 'Unknown recipe command.', [], ['acms mobile recipe list | add <name>']);
+  const all = await recipes();
+  const recipe = all.find((r) => r.name === args[0]);
+  if (!recipe) fail(args[0] ? 'NOT_FOUND' : 'USAGE', args[0] ? `No recipe named ${args[0]}.` : 'Name a recipe.', [], [`Recipes: ${all.map((r) => r.name).join(', ')}`]);
+  const app = await pickApp(flags.dir, recipe.kind);
+  if (app.kind !== recipe.kind) fail('USAGE', `${recipe.name} is a recipe for ${recipe.kind} apps, but ${app.dir}/ is a${app.kind === 'editor' ? 'n' : ''} ${app.kind} app; nothing was changed.`, [], [`Recipes for ${app.kind} apps: ${all.filter((r) => r.kind === app.kind).map((r) => r.name).join(', ')}`]);
+  const conflicts = [];
+  for (const f of recipe.files) if (await exists(join(app.dir, f))) conflicts.push(f);
+  if (conflicts.length && !flags.force) fail('EXISTS', `The ${recipe.name} recipe would overwrite files in ${app.dir}/; nothing was changed.`, conflicts, ['Move or rename those files, or use --force.']);
+  const pkg = await readJson(join(app.dir, 'package.json'));
+  const missing = recipe.packages.filter((p) => !pkg.dependencies?.[p] && !pkg.devDependencies?.[p]);
+  const install = missing.length ? `cd ${app.dir} && npx expo install ${missing.join(' ')}` : null;
+  const result = { recipe: recipe.name, kind: recipe.kind, app: app.dir, files: recipe.files.map((f) => `${app.dir}/${f}`), routes: recipe.routes, install, next: [...(install ? [install] : []), ...recipe.next] };
+  if (flags['dry-run']) return { dryRun: true, ...result };
+  const src = join(RECIPES, recipe.name, 'files');
+  for (const f of await walk(src)) {
+    await mkdir(dirname(join(app.dir, target(f))), { recursive: true });
+    await writeFile(join(app.dir, target(f)), await readFile(join(src, f)));
+  }
+  return { added: recipe.name, ...result };
+}
+
+export async function mobileCommand(sub, args, flags) {
+  if (sub === 'list') return { apps: await listApps() };
+  if (sub === 'dev') return mobileDev(flags);
+  if (sub === 'recipe') return recipeCommand(args[0], args.slice(1), flags);
+  fail('USAGE', 'Unknown mobile command.', [], ['acms add mobile [client|editor] | acms mobile list | dev | doctor | recipe list | recipe add <name>']);
+}

package/cli/native-sections.mjs

@@ -0,0 +1,168 @@
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { CORE, exists, fail, readJson } from './common.mjs';
+import { listApps } from './mobile.mjs';
+
+// Native twins of editable sections for the site's Expo app (mobile/):
+//   • library sections render from @acms-subir/native/sections by default;
+//     `section add <name> --native` copies an editable version into the app
+//   • `section new <type>` scaffolds a native stub typed from theme.json
+//   • `acms check` reports sections that only have a web version
+// Components live in <app>/sections/<Type>.tsx and are registered in
+// <app>/sections/index.ts, which the starter passes to <Sections registry>.
+
+const LIBRARY = join(CORE, 'section-library');
+export const pascal = (type) => type.split('-').map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+const rel = (path) => relative(process.cwd(), path).split(sep).join('/');
+
+/** Library section type → native component name (the web component's name). */
+export async function libraryComponents() {
+  const out = {};
+  for (const name of await readdir(LIBRARY).catch(() => [])) {
+    const raw = await readJson(join(LIBRARY, name, 'section.json')).catch(() => null);
+    if (raw) out[raw.type] = { name, component: raw.definition.component.split('/').pop().replace(/\.astro$/, ''), fields: Object.keys(raw.definition.fields) };
+  }
+  return out;
+}
+
+/** The app to write into: --dir, or the only app in this site. Null when there is none. */
+export async function targetApp(flags, { required = false } = {}) {
+  const apps = await listApps();
+  if (flags.dir) {
+    const app = apps.find((a) => a.dir === flags.dir.replace(/^\.\/|\/+$/g, ''));
+    if (!app) fail('NOT_FOUND', `${flags.dir} is not an ACMS mobile app.`, [], ['acms mobile list']);
+    return { app };
+  }
+  if (!apps.length) {
+    if (required) fail('NOT_FOUND', 'No mobile app found in this site; --native writes into one.', [], ['acms add mobile']);
+    return { app: null };
+  }
+  if (apps.length > 1) {
+    if (required) fail('USAGE', 'Several mobile apps found; choose one with --dir.', apps.map((a) => a.dir));
+    return { app: null, warning: `Several mobile apps found (${apps.map((a) => a.dir).join(', ')}); pass --dir to add a native version.` };
+  }
+  return { app: apps[0] };
+}
+
+// Package-relative imports of the packaged sources → public entry points.
+const IMPORTS = {
+  '../registry.js': '@acms-subir/native', '../hooks.js': '@acms-subir/native', '../navigation.js': '@acms-subir/native',
+  '../layout.js': '@acms-subir/native', '../format.js': '@acms-subir/native', '../components.js': '@acms-subir/native',
+  '../focus.js': '@acms-subir/native', '../links.js': '@acms-subir/native',
+  './shared.js': '@acms-subir/native/sections', './types.js': '@acms-subir/native/sections',
+};
+export function toAppSource(text, from, to) {
+  let out = text.replace(/from '(\.{1,2}\/[^']+)'/g, (m, path) => {
+    if (!IMPORTS[path]) throw new Error(`Unexpected import ${path}`);
+    return `from '${IMPORTS[path]}'`;
+  });
+  if (from !== to) out = out.replace(new RegExp(`export function ${from}\\(`), `export function ${to}(`);
+  return `// Editable copy of the packaged ${from} section from @acms-subir/native.\n// It overrides the packaged one through sections/index.ts; change it freely.\n${out}`;
+}
+
+async function packagedSource(app, component) {
+  const candidates = [
+    join(app.dir, 'node_modules/@acms-subir/native/src/sections', `${component}.tsx`),
+    join(CORE, '../native/src/sections', `${component}.tsx`),
+  ];
+  for (const file of candidates) if (await exists(file)) return readFile(file, 'utf8');
+  fail('NOT_INSTALLED', `The packaged ${component} source was not found.`, [], [`cd ${app.dir} && npm install`]);
+}
+
+const REGISTRY_TEMPLATE = join(CORE, 'mobile-template/client/sections/index.ts');
+
+/** Keys registered in <app>/sections/index.ts ("team", "hero-banner:cover"). */
+export function registryKeys(text) {
+  const start = text.indexOf('defineSectionRegistry(');
+  if (start < 0) return [];
+  const end = text.indexOf('});', start);
+  const body = text.slice(start, end < 0 ? undefined : end);
+  return [...body.matchAll(/^\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z_$][\w$]*))\s*:/gm)].map((m) => m[1] ?? m[2] ?? m[3]);
+}
+
+/** Adds `import { X } from './X'` and `'type': X` to the app's registry. */
+export async function register(app, type, component) {
+  const file = join(app.dir, 'sections/index.ts');
+  if (!(await exists(file))) { await mkdir(join(app.dir, 'sections'), { recursive: true }); await writeFile(file, await readFile(REGISTRY_TEMPLATE, 'utf8')); }
+  let text = await readFile(file, 'utf8');
+  if (registryKeys(text).includes(type)) return { registered: false, note: `sections/index.ts already registers “${type}”.` };
+  const importLine = `import { ${component} } from './${component}';`;
+  const entry = `  ${/^[a-z_$][\w$]*$/i.test(type) ? type : `'${type}'`}: ${component},`;
+  if (!text.includes(importLine)) {
+    text = text.includes('// acms:imports') ? text.replace(/^(\/\/ acms:imports)/m, `${importLine}\n$1`)
+      : text.replace(/((?:^import[^\n]*\n)+)/m, `$1${importLine}\n`);
+  }
+  if (text.includes('// acms:sections')) text = text.replace(/^(\s*\/\/ acms:sections)/m, `${entry}\n$1`);
+  else if (/defineSectionRegistry\(\{/.test(text)) text = text.replace(/defineSectionRegistry\(\{/, `defineSectionRegistry({\n${entry}`);
+  else return { registered: false, note: `Add ${entry.trim()} to your registry in sections/index.ts by hand.` };
+  await writeFile(file, text);
+  return { registered: true };
+}
+
+/** Plan (and with write=true, do) the editable copy of a library section. */
+export async function libraryTwin(app, name, type, flags, write) {
+  const raw = await readJson(join(LIBRARY, name, 'section.json'));
+  const from = raw.definition.component.split('/').pop().replace(/\.astro$/, '');
+  const to = pascal(type);
+  const file = join(app.dir, 'sections', `${to}.tsx`);
+  if ((await exists(file)) && !flags.force) fail('EXISTS', `${rel(file)} already exists.`, [], ['Use --force to replace it.']);
+  if (!write) return { app: app.dir, component: rel(file) };
+  const source = toAppSource(await packagedSource(app, from), from, to);
+  await mkdir(join(app.dir, 'sections'), { recursive: true });
+  await writeFile(file, source);
+  return { app: app.dir, component: rel(file), ...(await register(app, type, to)) };
+}
+
+/** A native stub for a new coded section, typed from the app's sections/types.ts. */
+export async function stubTwin(app, type, title, themeSlug, flags) {
+  const name = pascal(type);
+  const file = join(app.dir, 'sections', `${name}.tsx`);
+  if ((await exists(file)) && !flags.force) return { app: app.dir, component: rel(file), written: false, note: `${rel(file)} already exists; left unchanged.` };
+  await mkdir(join(app.dir, 'sections'), { recursive: true });
+  await writeFile(file, `import { Text, View } from 'react-native';
+import { useTheme, type SectionComponentProps } from '@acms-subir/native';
+import { Grid, SectionHeader } from '@acms-subir/native/sections';
+import type { ${name}Data } from './types';
+
+// Native version of the “${title}” section (src/themes/${themeSlug}/sections/${name}.astro).
+// Keep it in step with the web component: same fields, same variants. The
+// data arrives exactly as the Astro component receives it; ./types is
+// regenerated by \`npx acms check\` when theme.json changes.
+export function ${name}({ data }: SectionComponentProps<${name}Data>) {
+  const t = useTheme();
+  return (
+    <View>
+      <SectionHeader heading={data.heading} style={{ marginBottom: 20 }} />
+      <Grid minItem={224} gap={14}>
+        {data.items.filter((item) => item.title).map((item, i) => (
+          <View key={i} style={[t.styles.card, { flex: 1, gap: 6 }]}>
+            <Text style={t.styles.text.heading}>{item.title}</Text>
+            {!!item.text && <Text style={t.styles.text.muted}>{item.text}</Text>}
+          </View>
+        ))}
+      </Grid>
+    </View>
+  );
+}
+`);
+  return { app: app.dir, component: rel(file), written: true, ...(await register(app, type, name)) };
+}
+
+/** Which project sections the app renders natively; the rest show as a web view. */
+export async function nativeCoverage(manifest, library) {
+  const { app } = await targetApp({});
+  if (!app) return null;
+  const text = await readFile(join(app.dir, 'sections/index.ts'), 'utf8').catch(() => '');
+  const own = new Set(registryKeys(text).map((k) => k.split(':')[0]));
+  const out = { app: app.dir, native: [], library: [], webView: [], libraryFieldsNotShown: [] };
+  for (const [type, def] of Object.entries(manifest.sections ?? {})) {
+    if (own.has(type)) out.native.push(type);
+    else if (library[type]) {
+      out.library.push(type);
+      const extra = Object.keys(def.fields).filter((k) => !library[type].fields.includes(k));
+      if (extra.length) out.libraryFieldsNotShown.push({ type, fields: extra, hint: `The packaged ${library[type].component} ignores these; run acms section add ${library[type].name} --native --force to edit a copy.` });
+    } else out.webView.push(type);
+  }
+  if (out.webView.length) out.info = `${out.webView.length} section${out.webView.length > 1 ? 's have' : ' has'} no native version (${out.webView.join(', ')}); the app shows ${out.webView.length > 1 ? 'them' : 'it'} as the website renders ${out.webView.length > 1 ? 'them' : 'it'}. Write ${app.dir}/sections/<Type>.tsx and register it in ${app.dir}/sections/index.ts for a native look.`;
+  return out;
+}

package/cli/preview.mjs

@@ -1,4 +1,4 @@
-import { mkdir, writeFile, cp, symlink, mkdtemp, readFile } from 'node:fs/promises';
+import { mkdir, writeFile, cp, symlink, mkdtemp, readFile, stat } from 'node:fs/promises';
 import { join, resolve, dirname } from 'node:path';
 import { createRequire } from 'node:module';
 import { spawn, spawnSync } from 'node:child_process';
@@ -10,6 +10,8 @@ export async function prepareFixture(p,dir,slug){
   const req=createRequire(join(p.cwd,'package.json'));const astro=dirname(req.resolve('astro/package.json'));
   await symlink(dirname(astro),join(root,'node_modules'),'dir');
   await mkdir(join(root,'src/themes'),{recursive:true});await symlink(dir,join(root,'src/themes',slug),'dir');
+  // the project's public/ (videos, posters, fonts the theme links to by URL) serves as-is
+  const pub=join(p.cwd,'public');if(await stat(pub).then(s=>s.isDirectory(),()=>false))await symlink(pub,join(root,'public'),'dir');
   await mkdir(join(root,'src/pages/acms-theme-preview'),{recursive:true});await mkdir(join(root,'src/actions'),{recursive:true});
   await writeFile(join(root,'src/actions/index.ts'),"export { server } from '@acms-subir/core/actions';\n");
   await writeFile(join(root,'package.json'),JSON.stringify({name:'acms-isolated-preview',type:'module',private:true}));
@@ -31,8 +33,9 @@ await repo.updateSettings({activeTheme:${JSON.stringify(slug)}});
 return Astro.redirect('/');
 ---`);
   await writeFile(join(root,'src/pages/acms-theme-preview/index.astro'),`---\nconst routes=['/','/preview-about','/blog','/blog?page=2','/blog/preview-post-0','/events/preview-event','/calendar','/book','/search?q=Fixture','/404'];\n---\n<html><head><title>ACMS theme fixture controls</title></head><body><h1>Isolated theme preview</h1><p>Initialize synthetic data once, then inspect real ACMS routes. Empty lists and missing covers are intentional. Check phone, tablet and desktop layouts using the controls below.</p><a href='/acms-theme-preview/setup'>Initialize fixtures</a><nav>{routes.map(route=><p><a href={route} target='fixture'>{route}</a></p>)}</nav><p><a href='/?scheme=light' target='fixture'>Light</a> · <a href='/?scheme=dark' target='fixture'>Dark</a></p><p aria-label='Preview width'><button data-width='390px'>Phone</button> <button data-width='768px'>Tablet</button> <button data-width='100%'>Desktop</button></p><iframe id='fixture' name='fixture' title='Theme preview' src='/' style='width:100%;height:70vh;border:1px solid #999;max-width:100%'></iframe><script>document.querySelectorAll('button[data-width]').forEach(button=>button.addEventListener('click',()=>{const frame=document.getElementById('fixture');if(frame)frame.style.width=button.getAttribute('data-width')||'100%';}));</script></body></html>`);
-  const env={PATH:process.env.PATH,HOME:process.env.HOME,TMPDIR:process.env.TMPDIR,NODE_ENV:'development',SQLITE_URL:`file:${join(root,'fixture.db')}`,SESSION_SECRET:randomBytes(32).toString('hex'),ADMIN_PASSWORD:randomBytes(24).toString('hex'),ACMS_NO_UPDATE_CHECK:'1'};
-  return {root,astro:join(astro,'astro.js'),env};
+  const password=randomBytes(12).toString('hex');
+  const env={PATH:process.env.PATH,HOME:process.env.HOME,TMPDIR:process.env.TMPDIR,NODE_ENV:'development',SQLITE_URL:`file:${join(root,'fixture.db')}`,SESSION_SECRET:randomBytes(32).toString('hex'),ADMIN_PASSWORD:password,ACMS_NO_UPDATE_CHECK:'1'};
+  return {root,astro:join(astro,'astro.js'),env,password};
 }
 export async function buildFixture(p,dir,slug){
   const fixture=await prepareFixture(p,dir,slug);
@@ -42,7 +45,8 @@ export async function buildFixture(p,dir,slug){
 }
 export async function devFixture(p,dir,slug,flags){
   const f=await prepareFixture(p,dir,slug);const port=Number(flags.port??4322);if(!Number.isInteger(port)||port<1024||port>65535)fail('USAGE','Port must be 1024–65535.');
-  console.error(`Isolated preview: http://localhost:${port}/acms-theme-preview\nWorkspace: ${f.root}\nTheme sources are linked for live reload; fixture data stays isolated.`);
+  // a throwaway local-only server with synthetic data, so the password is safe to show
+  console.error(`Isolated preview: http://localhost:${port}/acms-theme-preview\nAdmin: http://localhost:${port}/admin  ·  password: ${f.password}\nWorkspace: ${f.root}\nTheme sources and public/ are linked for live reload; fixture data stays isolated.`);
   const child=spawn(process.execPath,[f.astro,'dev','--host','127.0.0.1','--port',String(port),...(!flags.json&&process.stdout.isTTY?['--open','/acms-theme-preview']:[])],{cwd:f.root,env:f.env,stdio:['ignore','pipe','pipe']});child.stdout.pipe(process.stderr);child.stderr.pipe(process.stderr);
   const stop=()=>child.kill('SIGTERM');process.once('SIGINT',stop);process.once('SIGTERM',stop);
   const exit=await new Promise((done,reject)=>{child.once('exit',done);child.once('error',reject);});process.removeListener('SIGINT',stop);process.removeListener('SIGTERM',stop);