@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/cli/doctor/fix.js

@@ -0,0 +1,66 @@
+// @ts-check
+'use strict';
+
+const { execInTerminal } = require('../exec');
+const { installPods } = require('../pods');
+const { codegen } = require('../codegen');
+const { icons } = require('../icons');
+const { links } = require('../links');
+const { setup } = require('../setup');
+
+/** @typedef {import('./types').Check} Check */
+
+/**
+ * Makes the fixes doctor can make, asking before each: setup shows its changes and asks, pod install runs in the
+ * terminal. The rest stays for the user, as the checks print it.
+ * @param {Check[]} checks
+ * @param {{
+ *   root: string;
+ *   ui: ReturnType<typeof import('../ui').createUI>;
+ *   inTerminal?: typeof execInTerminal;
+ *   interactive?: boolean;
+ * }} options
+ * @returns {Promise<boolean>} whether it ran any
+ */
+async function runFixes(
+  checks,
+  {
+    root,
+    ui,
+    inTerminal = execInTerminal,
+    interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  }
+) {
+  if (!interactive) {
+    ui.muted('  --fix asks before each fix, so it needs a terminal.');
+    return false;
+  }
+  // A warning with a fix the CLI can make is made too: the typed commands, the status bar of the template.
+  const runs = new Set(
+    checks.flatMap((check) =>
+      (check.status === 'error' || check.status === 'warn') && check.fix?.run ? [check.fix.run] : []
+    )
+  );
+  if (runs.size === 0) {
+    ui.muted('  Nothing --fix can do: the fixes above are yours to make.');
+    return false;
+  }
+  // Setup first: the app's files come before its pods. When the pods need a fix of their own, they are installed once,
+  // after the rest, not by setup too.
+  if (runs.has('setup')) {
+    await setup({ root, yes: false, dryRun: false, ui, header: false, skipPods: runs.has('pods') });
+  }
+  // The links of linking on the native side, and the icons from their settings.
+  if (runs.has('links')) await links({ root, yes: false, dryRun: false, ui });
+  if (runs.has('icons')) await icons({ root, options: {}, yes: false, dryRun: false, ui });
+  // The generated code of the native screens, from their props as they are now.
+  if (runs.has('codegen')) await codegen({ root, yes: false, dryRun: false, ui, header: false });
+  if (runs.has('pods') && (await ui.confirm('Run pod install?'))) {
+    ui.line('');
+    const pods = installPods({ root, json: false, inTerminal });
+    if (!pods.ok) ui.error(`pod install failed${pods.output}`);
+  }
+  return true;
+}
+
+module.exports = { runFixes };

package/cli/doctor/index.js

@@ -0,0 +1,136 @@
+// @ts-check
+'use strict';
+
+const os = require('node:os');
+const { PACKAGE, installedVersion, isSupported, reactNativeVersion } = require('../app');
+const { exec } = require('../exec');
+const { createUI } = require('../ui');
+const { androidChecks } = require('./checks/android');
+const { appChecks } = require('./checks/app');
+const { conflictChecks } = require('./checks/conflicts');
+const { deviceChecks } = require('./checks/devices');
+const { iosChecks } = require('./checks/ios');
+const { navigationChecks } = require('./checks/navigation');
+const { runFixes } = require('./fix');
+
+/** @typedef {import('./types').Check} Check */
+/** @typedef {import('./types').Context} Context */
+
+/** @type {[import('./types').Group, string][]} */
+const GROUPS = [
+  ['app', 'App'],
+  ['navigation', 'Navigation'],
+  ['android', 'Android'],
+  ['ios', 'iOS'],
+  ['devices', 'Devices'],
+  ['conflicts', 'Conflicts'],
+];
+
+/**
+ * Every check of the app.
+ * @param {Context} context
+ * @returns {Check[]}
+ */
+function collect(context) {
+  return [
+    ...appChecks(context),
+    ...navigationChecks(context),
+    ...androidChecks(context),
+    ...iosChecks(context),
+    ...deviceChecks(context),
+    ...conflictChecks(context),
+  ];
+}
+
+/**
+ * Checks what the navigation needs in the app; with `fix`, makes the fixes it can, with `json`, prints the checks as
+ * JSON for CI and tools.
+ * @param {{
+ *   root: string;
+ *   fix: boolean;
+ *   json: boolean;
+ *   ui?: ReturnType<typeof createUI>;
+ *   run?: import('../exec').Exec;
+ *   env?: NodeJS.ProcessEnv;
+ *   platform?: NodeJS.Platform;
+ *   home?: string;
+ *   write?: (text: string) => void;
+ * }} options
+ * @returns {Promise<number>} the exit code: 1 when a check found a problem
+ */
+async function doctor({
+  root,
+  fix,
+  json,
+  ui = createUI(),
+  run = exec,
+  env = process.env,
+  platform = process.platform,
+  home = os.homedir(),
+  write = (text) => process.stdout.write(text),
+}) {
+  if (fix && json) {
+    ui.error('--fix asks before each fix: run it without --json.');
+    return 1;
+  }
+  /** @type {Context} */
+  const context = { root, run, env, platform, home };
+  let checks = collect(context);
+  const failed = () => checks.some((check) => check.status === 'error');
+
+  if (json) {
+    write(JSON.stringify({ ok: !failed(), checks }, null, 2) + '\n');
+    return failed() ? 1 : 0;
+  }
+
+  const version = reactNativeVersion(root);
+  const navigation = installedVersion(root, PACKAGE);
+  ui.banner({
+    command: 'doctor',
+    facts: [
+      version
+        ? { text: `React Native ${version}`, ok: isSupported(version) }
+        : { text: 'React Native not found' },
+      { text: navigation ? `navigation ${navigation}` : 'navigation not installed' },
+    ],
+  });
+  report(ui, checks);
+
+  // A warning with a fix the CLI makes counts too: the typed commands, the status bar of the template.
+  const fixable = () =>
+    failed() || checks.some((check) => check.status === 'warn' && check.fix?.run !== undefined);
+  if (fix && fixable()) {
+    ui.line('');
+    if (await runFixes(checks, { root, ui })) {
+      checks = collect(context);
+      ui.line('');
+      ui.muted('  After the fixes');
+      report(ui, checks);
+    }
+  }
+  return failed() ? 1 : 0;
+}
+
+/**
+ * The checks by group, then how many found something.
+ * @param {Pick<import('../ui').UI, 'checks' | 'summary'>} ui
+ * @param {Check[]} checks
+ * @param {[import('./types').Group, string][]} [groups] the groups to show, with their titles
+ */
+function report(ui, checks, groups = GROUPS) {
+  ui.checks(
+    groups
+      .map(([group, title]) => ({
+        title,
+        checks: checks.filter((check) => check.group === group),
+      }))
+      .filter(({ checks: inGroup }) => inGroup.length > 0)
+  );
+  ui.summary({
+    errors: checks.filter(({ status }) => status === 'error').length,
+    warnings: checks.filter(({ status }) => status === 'warn').length,
+    passed: checks.filter(({ status }) => status === 'ok').length,
+  });
+}
+
+module.exports = { doctor, collect, report, GROUPS };

package/cli/doctor/types.js

@@ -0,0 +1,30 @@
+// @ts-check
+'use strict';
+
+/**
+ * One finding of doctor:
+ * - ok: as the navigation needs it;
+ * - warn: works, but likely to cause trouble;
+ * - error: the app won't build or start as it is; `fix` says how to fix it, and `run` names what `--fix` can do;
+ * - info: how something works in this app, nothing to fix.
+ * @typedef {'repository' | 'app' | 'navigation' | 'android' | 'ios' | 'devices' | 'conflicts'} Group
+ * @typedef {'ok' | 'warn' | 'error' | 'info'} Status
+ * @typedef {'setup' | 'codegen' | 'pods' | 'links' | 'icons'} FixRun
+ * @typedef {{ group: Group; title: string; status: Status; detail?: string; fix?: { label: string; run?: FixRun } }}
+ *   Check
+ */
+
+/**
+ * What the checks look at: the app, the machine, and how to ask its programs. `jdk`: 'active' (an app) needs JDK 17
+ * in use; 'installed' (this repository, whose scripts pick it per command) needs it installed.
+ * @typedef {{
+ *   root: string;
+ *   run: import('../exec').Exec;
+ *   env: NodeJS.ProcessEnv;
+ *   platform: NodeJS.Platform;
+ *   home: string;
+ *   jdk?: 'active' | 'installed';
+ * }} Context
+ */
+
+module.exports = {};

package/cli/exec.js

@@ -0,0 +1,34 @@
+// @ts-check
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+
+/**
+ * Runs a program and returns what it printed; `ok` is false when it couldn't run or failed. The CLI asks `git`,
+ * `java`, `xcodebuild`, `pod` and the React Native CLI this way, and tests give it a stand-in.
+ * @typedef {(command: string, args: string[], options?: { cwd?: string; timeout?: number }) =>
+ *   { ok: boolean; stdout: string; stderr: string }} Exec
+ */
+
+/** @type {Exec} */
+function exec(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    timeout: options.timeout ?? 60_000,
+  });
+  return { ok: result.status === 0, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+
+/**
+ * Runs a program with the terminal as its output, for the long ones the user watches (`pod install`); true when it
+ * succeeded.
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{ cwd?: string }} [options]
+ */
+function execInTerminal(command, args, options = {}) {
+  return spawnSync(command, args, { cwd: options.cwd, stdio: 'inherit' }).status === 0;
+}
+
+module.exports = { exec, execInTerminal };

package/cli/gradle.js

@@ -0,0 +1,142 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** @typedef {import('./changes').FileChange} FileChange */
+
+// The latest stable Compose BOM when the CLI was written; an app can move to a newer one.
+const COMPOSE_BOM = '2026.09.00';
+
+const HOW_TO = `Set up Jetpack Compose in the app:
+  android/build.gradle, in buildscript dependencies:
+    classpath("org.jetbrains.kotlin:compose-compiler-gradle-plugin:$kotlinVersion")
+  android/app/build.gradle:
+    apply plugin: "org.jetbrains.kotlin.plugin.compose"
+    android { buildFeatures { compose true } }
+    dependencies {
+        implementation(platform("androidx.compose:compose-bom:${COMPOSE_BOM}"))
+        implementation("androidx.compose.ui:ui")
+        implementation("androidx.compose.material3:material3")
+    }`;
+
+/**
+ * The changes of the Gradle files that set up Jetpack Compose in the app, as React Native's template has them: the
+ * Compose compiler plugin of the app's Kotlin version, `buildFeatures.compose`, and the BOM with UI and Material 3.
+ * `done` when the app has Compose; by hand when its files aren't as the template's.
+ * @param {import('./project').Project} project
+ * @returns {FileChange[]}
+ */
+function composeChanges(project) {
+  const { rootBuildGradle, appBuildGradle } = project;
+  if (
+    !rootBuildGradle ||
+    !appBuildGradle ||
+    !rootBuildGradle.endsWith('.gradle') ||
+    !appBuildGradle.endsWith('.gradle')
+  ) {
+    return [
+      manual(appBuildGradle ?? rootBuildGradle, "the Gradle files aren't those of the template"),
+    ];
+  }
+  const rootBefore = fs.readFileSync(rootBuildGradle, 'utf8');
+  const appBefore = fs.readFileSync(appBuildGradle, 'utf8');
+  if (
+    /androidx\.compose/.test(appBefore) &&
+    /compose-compiler-gradle-plugin|plugin\.compose/.test(rootBefore + appBefore)
+  ) {
+    return [
+      {
+        name: 'build.gradle',
+        platform: 'android',
+        file: appBuildGradle,
+        status: 'done',
+        note: 'Compose set up',
+      },
+    ];
+  }
+
+  const root = insertAfterLine(
+    rootBefore,
+    /^\s*classpath\(["']org\.jetbrains\.kotlin:kotlin-gradle-plugin["']\)\s*$/m,
+    (indent) =>
+      `${indent}classpath("org.jetbrains.kotlin:compose-compiler-gradle-plugin:$kotlinVersion")`
+  );
+  let app = insertAfterLine(
+    appBefore,
+    /^apply plugin: ["']org\.jetbrains\.kotlin\.android["']\s*$/m,
+    () => 'apply plugin: "org.jetbrains.kotlin.plugin.compose"'
+  );
+  app =
+    app &&
+    insertAfterLine(
+      app,
+      /^android \{\s*$/m,
+      () => '    buildFeatures {\n        compose true\n    }'
+    );
+  app =
+    app &&
+    insertAfterLine(app, /^dependencies \{\s*$/m, () =>
+      [
+        `    implementation(platform("androidx.compose:compose-bom:${COMPOSE_BOM}"))`,
+        '    implementation("androidx.compose.ui:ui")',
+        '    implementation("androidx.compose.material3:material3")',
+      ].join('\n')
+    );
+  if (!root || !app)
+    return [manual(appBuildGradle, "the Gradle files aren't those of the template")];
+  return [
+    {
+      name: path.join('android', 'build.gradle'),
+      platform: 'android',
+      file: rootBuildGradle,
+      status: 'change',
+      before: rootBefore,
+      next: root,
+      note: 'Compose compiler plugin',
+    },
+    {
+      name: path.join('android', 'app', 'build.gradle'),
+      platform: 'android',
+      file: appBuildGradle,
+      status: 'change',
+      before: appBefore,
+      next: app,
+      note: 'Jetpack Compose',
+    },
+  ];
+}
+
+/**
+ * The text with a line after the first line the pattern matches; undefined when none does.
+ * @param {string} text
+ * @param {RegExp} pattern
+ * @param {(indent: string) => string} line gets the indentation of the line found
+ * @returns {string | undefined}
+ */
+function insertAfterLine(text, pattern, line) {
+  const found = pattern.exec(text);
+  if (!found) return undefined;
+  const end = found.index + found[0].length;
+  const indent = /^\s*/.exec(found[0])?.[0].replace(/\n/g, '') ?? '';
+  return text.slice(0, end) + '\n' + line(indent) + text.slice(end);
+}
+
+/**
+ * @param {string | undefined} file
+ * @param {string} note
+ * @returns {FileChange}
+ */
+function manual(file, note) {
+  return {
+    name: 'build.gradle',
+    platform: 'android',
+    ...(file && { file }),
+    status: 'manual',
+    note: `${note}, see below`,
+    howTo: HOW_TO,
+  };
+}
+
+module.exports = { composeChanges, COMPOSE_BOM };

package/cli/icons/android.js

@@ -0,0 +1,173 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { madeFile, oldFile } = require('../splash/files');
+
+/** @typedef {import('../changes').FileChange} FileChange */
+/** @typedef {import('./images').IconImages} IconImages */
+
+const NAMES = [
+  'ic_launcher',
+  'ic_launcher_round',
+  'ic_launcher_foreground',
+  'ic_launcher_monochrome',
+];
+const COLOR_FILE = 'ic_launcher_background.xml';
+
+/**
+ * The Android icons made anew: the adaptive icon (Android 8+) of a color, the foreground and the monochrome layer
+ * (themed icons, Android 13+), and the square and round icons of Android 7 and older, per density. WebP icons of the
+ * same names go, as two files of one name don't build.
+ * @param {import('../project').Project} project
+ * @param {IconImages} images
+ * @param {string} background `#RRGGBB`
+ * @param {string} hash
+ * @returns {FileChange[]}
+ */
+function planAndroidIcons(project, images, background, hash) {
+  if (!project.manifest) return [];
+  const res = path.join(path.dirname(project.manifest), 'res');
+  /** @type {FileChange[]} */
+  const changes = [];
+  const monochrome = images.android.every((density) => density.monochrome);
+  for (const { density, foreground, monochrome: layer, legacy, round } of images.android) {
+    const dir = path.join(res, `mipmap-${density}`);
+    changes.push(
+      madeFile('android', path.join(dir, 'ic_launcher.png'), legacy, 'Android 7 and older'),
+      madeFile('android', path.join(dir, 'ic_launcher_round.png'), round, 'round, Android 7'),
+      madeFile('android', path.join(dir, 'ic_launcher_foreground.png'), foreground, 'adaptive icon')
+    );
+    if (layer) {
+      changes.push(
+        madeFile('android', path.join(dir, 'ic_launcher_monochrome.png'), layer, 'themed icon')
+      );
+    } else if (fs.existsSync(path.join(dir, 'ic_launcher_monochrome.png'))) {
+      changes.push(oldFile('android', path.join(dir, 'ic_launcher_monochrome.png')));
+    }
+    for (const name of NAMES) {
+      const webp = path.join(dir, `${name}.webp`);
+      if (fs.existsSync(webp))
+        changes.push({ ...oldFile('android', webp), note: 'a PNG takes its place' });
+    }
+  }
+  const adaptive = adaptiveIcon(monochrome);
+  for (const name of ['ic_launcher.xml', 'ic_launcher_round.xml']) {
+    changes.push(
+      madeFile('android', path.join(res, 'mipmap-anydpi-v26', name), adaptive, 'adaptive icon')
+    );
+  }
+  changes.push(colorChange(res, background, hash));
+  const manifest = manifestChange(project.manifest);
+  if (manifest) changes.push(manifest);
+  return changes;
+}
+
+/**
+ * The adaptive icon's file: its color, its foreground and, unless the icon is a ready image, its monochrome layer.
+ * @param {boolean} monochrome
+ */
+function adaptiveIcon(monochrome) {
+  return [
+    '<?xml version="1.0" encoding="utf-8"?>',
+    '<!-- Made by apex-navigation icons. -->',
+    '<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">',
+    '    <background android:drawable="@color/ic_launcher_background" />',
+    '    <foreground android:drawable="@mipmap/ic_launcher_foreground" />',
+    ...(monochrome ? ['    <monochrome android:drawable="@mipmap/ic_launcher_monochrome" />'] : []),
+    '</adaptive-icon>',
+    '',
+  ].join('\n');
+}
+
+/**
+ * The color behind the adaptive icon, with the hash of what the icon is made from. A color of that name in another
+ * values file would build twice: that file is left to change by hand.
+ * @param {string} res
+ * @param {string} background
+ * @param {string} hash
+ * @returns {FileChange}
+ */
+function colorChange(res, background, hash) {
+  const values = path.join(res, 'values');
+  const elsewhere = fs.existsSync(values)
+    ? fs
+        .readdirSync(values)
+        .filter((name) => name !== COLOR_FILE && name.endsWith('.xml'))
+        .find((name) =>
+          /<color\s+name="ic_launcher_background"/.test(
+            fs.readFileSync(path.join(values, name), 'utf8')
+          )
+        )
+    : undefined;
+  if (elsewhere) {
+    return {
+      name: elsewhere,
+      platform: 'android',
+      file: path.join(values, elsewhere),
+      status: 'manual',
+      note: 'has the color ic_launcher_background, see below',
+      howTo: `Remove <color name="ic_launcher_background"> from values/${elsewhere}: the icon's color is in values/${COLOR_FILE} now.`,
+    };
+  }
+  const text = [
+    '<?xml version="1.0" encoding="utf-8"?>',
+    '<resources>',
+    `    <!-- Made by apex-navigation icons (${hash}). -->`,
+    `    <color name="ic_launcher_background">${background}</color>`,
+    '</resources>',
+    '',
+  ].join('\n');
+  return madeFile('android', path.join(values, COLOR_FILE), text, background);
+}
+
+/**
+ * The manifest with the app's icons on `<application>`, when it names others or none; undefined when it names these.
+ * @param {string} file
+ * @returns {FileChange | undefined}
+ */
+function manifestChange(file) {
+  const before = fs.readFileSync(file, 'utf8');
+  const tag = /<application\b[^>]*>/.exec(before)?.[0];
+  if (!tag) return undefined;
+  let next = tag;
+  for (const [attribute, value] of [
+    ['android:icon', '@mipmap/ic_launcher'],
+    ['android:roundIcon', '@mipmap/ic_launcher_round'],
+  ]) {
+    const pattern = new RegExp(String.raw`${attribute}\s*=\s*"[^"]*"`);
+    if (pattern.test(next)) next = next.replace(pattern, `${attribute}="${value}"`);
+    else {
+      const end = next.endsWith('/>') ? '/>' : '>';
+      const head = next.slice(0, -end.length).trimEnd();
+      const indent = /\n([ \t]+)\S[^\n]*$/.exec(head)?.[1];
+      next = `${head}${indent ? `\n${indent}` : ' '}${attribute}="${value}"${end}`;
+    }
+  }
+  if (next === tag) return undefined;
+  return {
+    name: 'AndroidManifest.xml',
+    platform: 'android',
+    file,
+    status: 'change',
+    before,
+    // A function, so a `$` in the app's own attributes stays as it is.
+    next: before.replace(tag, () => next),
+    note: 'the icons of the app',
+  };
+}
+
+/**
+ * The hash in the color file the command made; undefined for icons made otherwise.
+ * @param {import('../project').Project} project
+ * @returns {string | undefined}
+ */
+function readColorHash(project) {
+  if (!project.manifest) return undefined;
+  const file = path.join(path.dirname(project.manifest), 'res', 'values', COLOR_FILE);
+  if (!fs.existsSync(file)) return undefined;
+  return /Made by apex-navigation icons \(([0-9a-f]+)\)/.exec(fs.readFileSync(file, 'utf8'))?.[1];
+}
+
+module.exports = { planAndroidIcons, readColorHash };