@radhya/mach 2.0.24 → 2.0.31

package/docs/deep-links.md

@@ -0,0 +1,173 @@
+# Deep Links
+
+Mach can configure the project-side pieces for:
+
+- iOS Universal Links
+- Android App Links
+- App URI schemes
+- Smart App Banner metadata when a web `index.html` exists
+
+## Setup
+
+Run the interactive flow:
+
+```bash
+mach deeplink setup
+```
+
+When run from the project root, Mach reads these values from `mach.config.json`:
+
+- `framework`
+- `scheme`
+- `ios.bundleIdentifier`
+- `android.package`
+- `ios.appleTeamId`
+- `ios.ascAppId`
+- `submit.<profile>.ios.appleTeamId`
+- `submit.<profile>.ios.ascAppId`
+
+Precedence is:
+
+```text
+command flags > existing deepLinks config > profile-specific config > root mach.config.json > Expo config inference > prompts/defaults
+```
+
+For most linked projects, this is enough:
+
+```bash
+mach deeplink setup --base-url https://app.example.com
+```
+
+Use `--profile` when the team/app metadata lives under a non-production submit profile:
+
+```bash
+mach deeplink setup --profile staging --base-url https://staging.example.com
+```
+
+Pass values directly only when you want to override config:
+
+```bash
+mach deeplink setup \
+  --yes \
+  --profile production \
+  --framework expo \
+  --platform all \
+  --base-url https://app.example.com \
+  --scheme example \
+  --ios-bundle-id com.example.app \
+  --apple-team-id ABCDE12345 \
+  --app-store-id 1234567890 \
+  --android-package com.example.app \
+  --android-fingerprint AA:BB:CC:DD \
+  --install-plugin \
+  --output public
+```
+
+`setup` writes:
+
+- compact `deepLinks` in `mach.config.json`
+- `public/.well-known/apple-app-site-association`
+- `public/.well-known/apple-app-site-association.json`
+- `public/apple-app-site-association`
+- `public/apple-app-site-association.json`
+- `public/.well-known/assetlinks.json`
+
+When `--output` is not provided, Mach uses `public` if that folder exists; otherwise it writes to `deep-links` and prints a hosting note.
+
+`mach.config.json` is the only Mach deep-link source of truth. Values already available from the selected profile or root config are not duplicated inside `deepLinks`. A typical generated block is intentionally small:
+
+```json
+{
+  "scheme": "example",
+  "ios": {
+    "bundleIdentifier": "com.example.app",
+    "appleTeamId": "ABCDE12345"
+  },
+  "android": {
+    "package": "com.example.app"
+  },
+  "deepLinks": {
+    "baseUrl": "https://app.example.com",
+    "web": {
+      "outputDir": "public"
+    }
+  }
+}
+```
+
+## Expo Projects
+
+For Expo projects, Mach wires a config plugin that applies:
+
+- `scheme`
+- `extra.deepLinkBaseUrl`
+- `ios.associatedDomains`
+- `android.intentFilters`
+
+The plugin reads from `mach.config.json`; it does not require or create a second deep-link JSON file.
+
+When `@radhya/mach` is installed in the app project, Mach uses the packaged plugin:
+
+```ts
+plugins: ['@radhya/mach/expo-plugin']
+```
+
+If the package is not installed, interactive `mach deeplink setup` asks to install it. `mach deeplink setup --yes` and `mach deeplink setup --install-plugin` install it automatically using the detected package manager.
+
+Use `mach deeplink setup --no-install-plugin` when you want to avoid changing `package.json`; if `@radhya/mach` is missing, Mach uses the local fallback instead.
+
+When the app only uses a global or `npx` Mach CLI and the package is not installed, Mach generates a local fallback:
+
+```text
+plugins/withMachDeepLinks.js
+```
+
+and wires:
+
+```ts
+plugins: ['./plugins/withMachDeepLinks']
+```
+
+This fallback keeps Expo and EAS builds working because the app project can resolve the plugin without depending on a global CLI install.
+
+If the project uses `app.json` or `app.config.json`, Mach inserts the plugin automatically.
+
+If the project uses `app.config.ts` or `app.config.js`, Mach inserts the plugin automatically when it can find a normal `plugins: [` array. If the dynamic config is too custom to patch safely, Mach prints the exact plugin entry to add:
+
+```ts
+export default {
+  expo: {
+    plugins: ['@radhya/mach/expo-plugin'],
+  },
+}
+```
+
+## Verify
+
+Verify local files:
+
+```bash
+mach deeplink verify
+```
+
+Check hosted files too:
+
+```bash
+mach deeplink verify --live
+```
+
+Print Android device verification commands:
+
+```bash
+mach deeplink verify --android-device
+```
+
+Live verification checks:
+
+- `https://<domain>/.well-known/apple-app-site-association`
+- `https://<domain>/apple-app-site-association`
+- `https://<domain>/.well-known/assetlinks.json`
+
+## Current Scope
+
+The first implementation generates hosted files and Expo integration. Vanilla React Native native file patching is intentionally conservative in this phase: verification reports missing Android manifest or iOS entitlement entries, but setup does not mutate native XML or Xcode project files yet.

package/expo-plugin/index.js

@@ -0,0 +1,119 @@
+const fs = require('fs')
+const path = require('path')
+
+const unique = values => Array.from(new Set(values.filter(Boolean)))
+const nonEmpty = value => typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined
+const first = (...values) => values.map(nonEmpty).find(Boolean)
+
+const sanitizeScheme = value => {
+  const normalized = nonEmpty(value)
+  if (!normalized) return 'app'
+  return normalized
+    .toLowerCase()
+    .replace(/[^a-z0-9+.-]/g, '-')
+    .replace(/^-+|-+$/g, '') || 'app'
+}
+
+const normalizeBaseUrl = value => {
+  const normalized = nonEmpty(value)
+  if (!normalized) return undefined
+  const parsed = new URL(normalized.includes('://') ? normalized : `https://${normalized}`)
+  const pathname = parsed.pathname === '/' ? '' : parsed.pathname.replace(/\/+$/, '')
+  return `${parsed.protocol}//${parsed.host}${pathname}`
+}
+
+const domainFromBaseUrl = value => {
+  try {
+    const normalized = normalizeBaseUrl(value)
+    return normalized ? new URL(normalized).hostname : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const readMachConfig = config => {
+  const projectRoot = config && config._internal && config._internal.projectRoot
+    ? config._internal.projectRoot
+    : process.cwd()
+  const configPath = path.join(projectRoot, 'mach.config.json')
+  if (!fs.existsSync(configPath)) return {}
+  return JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+}
+
+const resolveBuildProfile = (machConfig, name, seen = new Set()) => {
+  const profiles = machConfig.build || {}
+  const profile = profiles[name]
+  if (!profile || typeof profile !== 'object') return {}
+  if (seen.has(name)) throw new Error(`Circular Mach build profile inheritance: ${name}`)
+  seen.add(name)
+
+  if (!profile.extends) return { ...profile }
+  const parent = resolveBuildProfile(machConfig, profile.extends, seen)
+  return {
+    ...parent,
+    ...profile,
+    env: { ...(parent.env || {}), ...(profile.env || {}) },
+    ios: { ...(parent.ios || {}), ...(profile.ios || {}) },
+    android: { ...(parent.android || {}), ...(profile.android || {}) },
+  }
+}
+
+const hasDomainFilter = (filter, domain) => {
+  const data = Array.isArray(filter && filter.data) ? filter.data : []
+  return data.some(item => item && item.scheme === 'https' && item.host === domain)
+}
+
+const resolveDeepLinks = config => {
+  const machConfig = readMachConfig(config)
+  const deepLinks = machConfig.deepLinks || {}
+  const profileName = deepLinks.profile || process.env.MACH_PROFILE || process.env.EAS_BUILD_PROFILE || 'production'
+  const profile = resolveBuildProfile(machConfig, profileName)
+  const baseUrl = normalizeBaseUrl(deepLinks.baseUrl)
+  const domain = first(deepLinks.domain, domainFromBaseUrl(baseUrl))
+  const scheme = sanitizeScheme(first(
+    deepLinks.scheme,
+    profile.ios && profile.ios.scheme,
+    machConfig.scheme,
+    config.scheme,
+    machConfig.slug,
+    machConfig.name,
+    config.slug,
+    config.name,
+    'app'
+  ))
+
+  return { ...deepLinks, baseUrl, domain, scheme }
+}
+
+module.exports = function withMachDeepLinks(config) {
+  const deepLinks = resolveDeepLinks(config)
+  if (!deepLinks.baseUrl || !deepLinks.domain) return config
+
+  config.scheme = deepLinks.scheme
+  config.extra = { ...(config.extra || {}), deepLinkBaseUrl: deepLinks.baseUrl }
+
+  config.ios = config.ios || {}
+  config.ios.associatedDomains = unique([
+    ...(config.ios.associatedDomains || []),
+    deepLinks.domain ? `applinks:${deepLinks.domain}` : null,
+    deepLinks.ios && deepLinks.ios.webCredentials ? `webcredentials:${deepLinks.domain}` : null,
+    deepLinks.ios && deepLinks.ios.activityContinuation ? `activitycontinuation:${deepLinks.domain}` : null,
+  ])
+
+  config.android = config.android || {}
+  const intentFilters = Array.isArray(config.android.intentFilters)
+    ? config.android.intentFilters
+    : []
+
+  if (!intentFilters.some(filter => hasDomainFilter(filter, deepLinks.domain))) {
+    intentFilters.push({
+      action: 'VIEW',
+      autoVerify: true,
+      data: [{ scheme: 'https', host: deepLinks.domain, pathPattern: '.*' }],
+      category: ['BROWSABLE', 'DEFAULT'],
+    })
+  }
+
+  config.android.intentFilters = intentFilters
+  return config
+}

package/expo-plugin/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "commonjs",
+  "main": "index.js"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radhya/mach",
-  "version": "2.0.24",
+  "version": "2.0.31",
   "description": "Mach CLI: Cloud Build Orchestrator for React Native & Expo",
   "main": "dist/index.js",
   "type": "module",
@@ -9,7 +9,9 @@
   },
   "files": [
     "dist/",
-    "docs/frameworks/"
+    "expo-plugin/",
+    "docs/frameworks/",
+    "docs/deep-links.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/commands/isolated-upload.ts --format esm --clean --minify --dts",