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

package/cli/index.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+// @ts-check
+'use strict';
+
+const path = require('node:path');
+const { parseArgs } = require('node:util');
+const { codegen } = require('./codegen');
+const { doctor } = require('./doctor');
+const { icons } = require('./icons');
+const { info } = require('./info');
+const { init } = require('./init');
+const { links, linksFiles, linksOpen } = require('./links');
+const { mcp, mcpInstall } = require('./mcp');
+const { migrate } = require('./migrate');
+const { screen } = require('./screen');
+const { setup } = require('./setup');
+const { upgrade } = require('./upgrade');
+const { splash } = require('./splash');
+
+const HELP = `Usage: apex-navigation <command> [options]
+
+Commands:
+  init Name    Makes a new React Native app with the navigation set up: Home and Details in a stack, its
+               dependencies and pods installed.
+  setup        Sets up the app for the navigation: its native files and its entry point, the types of its
+               commands, then the pods.
+  screen Name  Adds a screen: its file, with its props and options, and its line in screens. A native screen
+               (--native, --ios, --android) also gets its Swift and Kotlin files and its generated code.
+  codegen      Generates the Swift and Kotlin side of the native screens from their props in TypeScript, with
+               the typed commands of native code.
+  links        Declares the links of linking on the native side: the schemes in Info.plist and the manifest, the
+               web sites in the entitlements and a verified filter of the manifest.
+  links open url
+               Opens a link as a tap would, on the booted iOS simulator and the connected Android device.
+  links files  Writes the files the app's web site serves for its links: apple-app-site-association and
+               assetlinks.json.
+  icons        Makes the app icon of both platforms from a logo and a color, or from a ready square icon.
+               Without options, makes it again from the settings in package.json.
+  splash       Makes the native splash from a logo and colors, light and dark: a storyboard on iOS, a splash
+               theme on Android. Without options, makes it again from the settings in package.json.
+  migrate      Moves the app from react-native-navigation or React Navigation: the package, the native files and
+               what it can of the code; the rest is a report, place by place, with the step of the guide.
+  upgrade [version]
+               Upgrades the navigation (latest by default): the package, then its setup, codegen and pods, and
+               what changed since the version the app has.
+  doctor       Checks what the navigation needs in the app and on this machine.
+  info         Prints what the app is made with and what builds it, to paste into an issue.
+  mcp          Runs the MCP server on stdio, for AI coding agents: the commands, the map of the app, the docs.
+  mcp install client
+               Adds the server to the config of claude, cursor or vscode in the project, or prints the line for
+               codex.
+
+Options:
+  --yes        Applies the changes without asking.
+  --dry-run    Shows the changes and writes nothing.
+  --dir path   screen: the folder of the app's screens, from its root (src/screens by default); kept in
+               package.json for the next screens.
+  --native     screen: a native screen on both platforms, SwiftUI and Jetpack Compose.
+  --ios kind   screen: a native screen on iOS, swiftui or uikit (alone: iOS only).
+  --android k  screen: a native screen on Android, compose or views (alone: Android only).
+  --version v  init: the React Native of the app, a version or a tag (the one the navigation was checked
+               with by default).
+  --template name
+               init: the starter, stack (Home and Details, the default), tabs (Home, Profile, Settings) or auth
+               (Login, then the tabs).
+  --pm name    init: npm, yarn or bun (the one the command was run with by default).
+  --directory  init: the folder of the app (its name by default).
+  --package-name id
+               init: the Android package and iOS bundle id, such as com.example.app.
+  --title text init: the name the app shows.
+  --skip-install
+               init: makes the app without installing its dependencies and pods.
+  --skip-pods  init, setup, migrate: leaves the pods for later.
+  --root path  mcp: the app it serves (the folder the client starts it in by default).
+  --from name  migrate: react-native-navigation or react-navigation (the one in package.json by default).
+  --skip-git-init
+               init: no git repository.
+  --image path icons: a ready square icon, at least 1024 px, instead of --logo.
+  --logo-size n
+               icons: the logo's width in percent of the icon (60 by default).
+  --logo path  splash, icons: the logo, PNG, JPEG, WebP or SVG.
+  --background color
+               splash, icons: the background, such as #FFFFFF (the default).
+  --dark-logo path, --dark-background color
+               splash: the same in dark mode (the light ones without them); icons: --dark-logo only.
+  --logo-width n
+               splash: the logo's width in points and dp (100 by default; within 192 on Android 12+).
+  --fix        doctor: makes the fixes it can (setup, links, icons, codegen, pod install), asking
+               before each.
+  --platform ios|android
+               links open, links files: that platform only.
+  --cold       links open: quits the app first, so the link launches it.
+  --team-id id links files: the team of the Apple Developer account (the Xcode project's by default).
+  --fingerprint sha256
+               links files: the SHA-256 of a signing key for assetlinks.json, such as the release key of Google
+               Play signing; repeat it for several. The debug key's is added by itself.
+  --out path   links files: the folder of the files (.well-known by default).
+  --json       Prints the result as one JSON document, for CI, tools and AI agents. A command that changes files
+               writes them only with --yes.
+  --help       Shows this help.
+
+Exit codes: 0 done (or nothing to do), 1 a problem, or files left to change by hand.`;
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      yes: { type: 'boolean' },
+      'dry-run': { type: 'boolean' },
+      dir: { type: 'string' },
+      native: { type: 'boolean' },
+      ios: { type: 'string' },
+      android: { type: 'string' },
+      fix: { type: 'boolean' },
+      version: { type: 'string' },
+      pm: { type: 'string' },
+      directory: { type: 'string' },
+      'package-name': { type: 'string' },
+      title: { type: 'string' },
+      'skip-install': { type: 'boolean' },
+      'skip-pods': { type: 'boolean' },
+      'skip-git-init': { type: 'boolean' },
+      template: { type: 'string' },
+      platform: { type: 'string' },
+      cold: { type: 'boolean' },
+      'team-id': { type: 'string' },
+      fingerprint: { type: 'string', multiple: true },
+      out: { type: 'string' },
+      from: { type: 'string' },
+      root: { type: 'string' },
+      image: { type: 'string' },
+      'logo-size': { type: 'string' },
+      logo: { type: 'string' },
+      background: { type: 'string' },
+      'dark-logo': { type: 'string' },
+      'dark-background': { type: 'string' },
+      'logo-width': { type: 'string' },
+      json: { type: 'boolean' },
+      help: { type: 'boolean' },
+    },
+  });
+  const [command] = positionals;
+  if (values.help || command === undefined || command === 'help') {
+    console.log(HELP);
+    return 0;
+  }
+  if (command === 'init') {
+    return init({
+      cwd: process.cwd(),
+      name: positionals[1],
+      version: values.version,
+      pm: values.pm,
+      directory: values.directory,
+      packageName: values['package-name'],
+      title: values.title,
+      template: values.template,
+      skipGitInit: Boolean(values['skip-git-init']),
+      skipInstall: Boolean(values['skip-install']),
+      skipPods: Boolean(values['skip-pods']),
+      yes: Boolean(values.yes),
+      dryRun: Boolean(values['dry-run']),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'setup') {
+    return setup({
+      root: process.cwd(),
+      skipPods: Boolean(values['skip-pods']),
+      yes: Boolean(values.yes),
+      dryRun: Boolean(values['dry-run']),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'screen') {
+    return screen({
+      root: process.cwd(),
+      name: positionals[1],
+      dir: values.dir,
+      native: Boolean(values.native),
+      ios: values.ios,
+      android: values.android,
+      yes: Boolean(values.yes),
+      dryRun: Boolean(values['dry-run']),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'codegen') {
+    return codegen({
+      root: process.cwd(),
+      yes: Boolean(values.yes),
+      dryRun: Boolean(values['dry-run']),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'splash') {
+    return splash({
+      root: process.cwd(),
+      options: {
+        logo: values.logo,
+        background: values.background,
+        darkLogo: values['dark-logo'],
+        darkBackground: values['dark-background'],
+        logoWidth: values['logo-width'],
+      },
+      yes: Boolean(values.yes),
+      dryRun: Boolean(values['dry-run']),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'icons') {
+    return icons({
+      root: process.cwd(),
+      options: {
+        logo: values.logo,
+        image: values.image,
+        background: values.background,
+        darkLogo: values['dark-logo'],
+        logoSize: values['logo-size'],
+      },
+      yes: Boolean(values.yes),
+      dryRun: Boolean(values['dry-run']),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'upgrade') {
+    return upgrade({
+      root: process.cwd(),
+      version: positionals[1],
+      yes: Boolean(values.yes),
+      dryRun: Boolean(values['dry-run']),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'migrate') {
+    return migrate({
+      root: process.cwd(),
+      from: values.from,
+      skipPods: Boolean(values['skip-pods']),
+      yes: Boolean(values.yes),
+      dryRun: Boolean(values['dry-run']),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'mcp' && positionals[1] === 'install') {
+    return mcpInstall({
+      root: process.cwd(),
+      client: positionals[2],
+      yes: Boolean(values.yes),
+      dryRun: Boolean(values['dry-run']),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'mcp') {
+    return mcp({ root: values.root ? path.resolve(values.root) : process.cwd() });
+  }
+  if (command === 'info') {
+    return info({ root: process.cwd(), json: Boolean(values.json) });
+  }
+  if (command === 'links' && positionals[1] === 'open') {
+    return linksOpen({
+      root: process.cwd(),
+      url: positionals[2],
+      platform: values.platform,
+      cold: Boolean(values.cold),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'links' && positionals[1] === 'files') {
+    return linksFiles({
+      root: process.cwd(),
+      teamId: values['team-id'],
+      fingerprints: values.fingerprint,
+      out: values.out,
+      platform: values.platform,
+      yes: Boolean(values.yes),
+      dryRun: Boolean(values['dry-run']),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'links' && positionals[1] === undefined) {
+    return links({
+      root: process.cwd(),
+      yes: Boolean(values.yes),
+      dryRun: Boolean(values['dry-run']),
+      json: Boolean(values.json),
+    });
+  }
+  if (command === 'links') {
+    console.error(`Unknown command "links ${positionals[1]}": links, links open or links files.`);
+    return 1;
+  }
+  if (command === 'doctor') {
+    return doctor({ root: process.cwd(), fix: Boolean(values.fix), json: Boolean(values.json) });
+  }
+  console.error(`Unknown command "${command}".\n\n${HELP}`);
+  return 1;
+}
+
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+);

package/cli/info/index.js

@@ -0,0 +1,290 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { PACKAGE, installedVersion, isSupported, reactNativeVersion, usesExpo } = require('../app');
+const { sdkDir } = require('../doctor/checks/android');
+const { exec } = require('../exec');
+const { findProject } = require('../project');
+const { findConfig, loadTypeScript, navigationModule } = require('../typescript');
+
+/**
+ * What the app is made with and what builds it, for an issue: each value as its program or file says it, `null` where
+ * the CLI couldn't find it; `android.sdk` is the newest SDK platform installed. `mode`: `one-tree` when the app renders every screen in one React tree (`appProvider`),
+ * `root-per-screen` otherwise.
+ * @typedef {{
+ *   os: string;
+ *   node: string;
+ *   packageManager: string | null;
+ *   reactNative: string | null;
+ *   newArchitecture: boolean;
+ *   navigation: string | null;
+ *   mode: 'one-tree' | 'root-per-screen' | null;
+ *   expo: boolean;
+ *   ios: { xcode: string | null; cocoapods: string | null; deploymentTarget: string | null } | null;
+ *   android: {
+ *     jdk: string | null;
+ *     sdk: string | null;
+ *     compileSdk: string | null;
+ *     minSdk: string | null;
+ *     targetSdk: string | null;
+ *     gradle: string | null;
+ *   } | null;
+ * }} Info
+ */
+
+/**
+ * Prints what the app is made with and what builds it: Markdown to paste into an issue, or with `json` one JSON
+ * document. Changes nothing.
+ * @param {{
+ *   root: string;
+ *   json: boolean;
+ *   run?: import('../exec').Exec;
+ *   env?: NodeJS.ProcessEnv;
+ *   platform?: NodeJS.Platform;
+ *   home?: string;
+ *   write?: (text: string) => void;
+ * }} options
+ * @returns {Promise<number>} the exit code: 1 outside an app
+ */
+async function info({
+  root,
+  json,
+  run = exec,
+  env = process.env,
+  platform = process.platform,
+  home = os.homedir(),
+  write = (text) => process.stdout.write(text),
+}) {
+  if (!fs.existsSync(path.join(root, 'package.json'))) {
+    const message = 'No package.json here: run the command in the root of your app.';
+    if (json) {
+      write(
+        JSON.stringify(
+          { command: 'info', ok: false, errors: [{ code: 'app-missing', message }] },
+          null,
+          2
+        ) + '\n'
+      );
+    } else {
+      process.stderr.write(message + '\n');
+    }
+    return 1;
+  }
+  const found = collect({ root, run, env, platform, home });
+  if (json) {
+    write(JSON.stringify({ command: 'info', ok: true, info: found }, null, 2) + '\n');
+  } else {
+    write(markdown(found));
+  }
+  return 0;
+}
+
+/**
+ * @param {{
+ *   root: string;
+ *   run: import('../exec').Exec;
+ *   env: NodeJS.ProcessEnv;
+ *   platform: NodeJS.Platform;
+ *   home: string;
+ * }} context
+ * @returns {Info}
+ */
+function collect({ root, run, env, platform, home }) {
+  const reactNative = reactNativeVersion(root) ?? null;
+  // The React Native CLI takes a few seconds to say where the app's files are: asked once.
+  const project = findProject(root, run);
+  const ios = path.join(root, 'ios');
+  const android = path.join(root, 'android');
+  return {
+    os: system(run, platform),
+    node: process.versions.node,
+    packageManager: packageManager(root, run),
+    reactNative,
+    // The navigation runs on the New Architecture only, the one React Native has had alone since 0.82.
+    newArchitecture: reactNative !== null && isSupported(reactNative),
+    navigation: installedVersion(root, PACKAGE) ?? null,
+    mode: mode(project),
+    expo: usesExpo(root),
+    ios:
+      platform === 'darwin' && fs.existsSync(path.join(ios, 'Podfile'))
+        ? {
+            xcode: firstLine(run('xcodebuild', ['-version']))?.replace(/^Xcode\s*/, '') ?? null,
+            cocoapods: firstLine(
+              fs.existsSync(path.join(root, 'Gemfile'))
+                ? run('bundle', ['exec', 'pod', '--version'], { cwd: root })
+                : run('pod', ['--version'], { cwd: root })
+            ),
+            deploymentTarget: deploymentTarget(project),
+          }
+        : null,
+    android: fs.existsSync(path.join(android, 'build.gradle'))
+      ? androidInfo({ root, run, env, platform, home }, android)
+      : null,
+  };
+}
+
+/**
+ * The system and its processor, such as `macOS 27.0 (arm64)`.
+ * @param {import('../exec').Exec} run
+ * @param {NodeJS.Platform} platform
+ */
+function system(run, platform) {
+  if (platform === 'darwin') {
+    const version = firstLine(run('sw_vers', ['-productVersion']));
+    return `macOS ${version ?? os.release()} (${os.arch()})`;
+  }
+  return `${platform === 'win32' ? 'Windows' : os.type()} ${os.release()} (${os.arch()})`;
+}
+
+/**
+ * The package manager of the app's lock file, with the version that runs here.
+ * @param {string} root
+ * @param {import('../exec').Exec} run
+ * @returns {string | null}
+ */
+function packageManager(root, run) {
+  const managers = /** @type {const} */ ([
+    ['yarn.lock', 'yarn'],
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['bun.lock', 'bun'],
+    ['bun.lockb', 'bun'],
+    ['package-lock.json', 'npm'],
+  ]);
+  const manager = managers.find(([lock]) => fs.existsSync(path.join(root, lock)))?.[1];
+  if (!manager) return null;
+  const version = firstLine(run(manager, ['--version'], { cwd: root }));
+  return version ? `${manager} ${version}` : manager;
+}
+
+/**
+ * How the app renders its screens, from `appProvider` of `createNavigation`; null when the CLI can't read the app's
+ * code.
+ * @param {import('../project').Project} project
+ * @returns {Info['mode']}
+ */
+function mode(project) {
+  const ts = loadTypeScript(project.root);
+  const entry = project.entry;
+  const navigation = ts && entry && navigationModule(ts, entry);
+  if (!ts || !navigation) return null;
+  return findConfig(ts, navigation, 'appProvider') ? 'one-tree' : 'root-per-screen';
+}
+
+/**
+ * The oldest iOS the app runs on: the app target's in the Xcode project.
+ * @param {import('../project').Project} project
+ * @returns {string | null}
+ */
+function deploymentTarget(project) {
+  const text = project.xcodeProject ? read(project.xcodeProject) : undefined;
+  return (text && /IPHONEOS_DEPLOYMENT_TARGET = ([\d.]+);/.exec(text)?.[1]) ?? null;
+}
+
+/**
+ * @param {{
+ *   root: string;
+ *   run: import('../exec').Exec;
+ *   env: NodeJS.ProcessEnv;
+ *   platform: NodeJS.Platform;
+ *   home: string;
+ * }} context
+ * @param {string} android the app's android/ folder
+ * @returns {Info['android']}
+ */
+function androidInfo(context, android) {
+  const gradle = read(path.join(android, 'build.gradle')) ?? '';
+  const ext = (/** @type {string} */ name) =>
+    new RegExp(String.raw`\b${name}\s*=\s*"?([\w.]+)"?`).exec(gradle)?.[1] ?? null;
+  const java = context.env.JAVA_HOME ? path.join(context.env.JAVA_HOME, 'bin', 'java') : 'java';
+  const javaResult = context.run(java, ['-version']);
+  // `java -version` prints to stderr: `openjdk version "17.0.12" …`.
+  const jdk = javaResult.ok
+    ? (/version "([^"]+)"/.exec(javaResult.stderr || javaResult.stdout)?.[1] ?? null)
+    : null;
+  const sdk = sdkDir(context, android);
+  const wrapper = read(path.join(android, 'gradle', 'wrapper', 'gradle-wrapper.properties')) ?? '';
+  return {
+    jdk,
+    sdk: newestPlatform(sdk),
+    compileSdk: ext('compileSdkVersion'),
+    minSdk: ext('minSdkVersion'),
+    targetSdk: ext('targetSdkVersion'),
+    gradle: /gradle-([\d.]+)-(?:bin|all)\.zip/.exec(wrapper)?.[1] ?? null,
+  };
+}
+
+/**
+ * The newest SDK platform installed, such as `37` or `36.1`; null without the SDK.
+ * @param {string} sdk the folder of the Android SDK
+ * @returns {string | null}
+ */
+function newestPlatform(sdk) {
+  let names;
+  try {
+    names = fs.readdirSync(path.join(sdk, 'platforms'));
+  } catch {
+    return null;
+  }
+  const versions = names.flatMap((name) => /^android-([\d.]+)$/.exec(name)?.[1] ?? []);
+  versions.sort((a, b) => Number(a) - Number(b));
+  return versions.at(-1) ?? null;
+}
+
+/**
+ * The lines to paste into an issue.
+ * @param {Info} found
+ * @returns {string}
+ */
+function markdown(found) {
+  const or = (/** @type {string | null} */ value) => value ?? 'not found';
+  const lines = [
+    `- OS: ${found.os}`,
+    `- Node: ${found.node}${found.packageManager ? ` · ${found.packageManager}` : ''}`,
+    `- React Native: ${or(found.reactNative)}${found.newArchitecture ? ' · New Architecture' : ''}`,
+    `- ${PACKAGE}: ${or(found.navigation)}${
+      found.mode
+        ? ` · ${found.mode === 'one-tree' ? 'one React tree' : 'a React root per screen'}`
+        : ''
+    }`,
+    `- Expo: ${found.expo ? 'yes' : 'no'}`,
+  ];
+  if (found.ios) {
+    lines.push(
+      `- iOS: Xcode ${or(found.ios.xcode)} · CocoaPods ${or(found.ios.cocoapods)} · deployment target ${or(found.ios.deploymentTarget)}`
+    );
+  }
+  if (found.android) {
+    const { jdk, sdk, compileSdk, minSdk, targetSdk, gradle } = found.android;
+    lines.push(
+      `- Android: JDK ${or(jdk)} · Android SDK ${or(sdk)} · compileSdk ${or(compileSdk)} · minSdk ${or(minSdk)} · targetSdk ${or(targetSdk)} · Gradle ${or(gradle)}`
+    );
+  }
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * The first line a program printed, when it ran.
+ * @param {{ ok: boolean; stdout: string }} result
+ * @returns {string | null}
+ */
+function firstLine(result) {
+  const line = result.ok ? result.stdout.trim().split('\n')[0]?.trim() : '';
+  return line || null;
+}
+
+/**
+ * @param {string} file
+ * @returns {string | undefined}
+ */
+function read(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
+module.exports = { info, collect, markdown };