@radhya/mach 2.4.4 → 2.6.0

package/docs/deep-links.md

@@ -165,6 +165,21 @@ export default {
 }
 ```
 
+## Flutter Projects
+
+For Flutter applications, setup makes conservative, idempotent native changes:
+
+- adds verified HTTPS App Links and the custom URI scheme to the launcher activity;
+- adds `applinks:<domain>` to the Runner entitlements;
+- connects `CODE_SIGN_ENTITLEMENTS` when the Runner target can be identified;
+- adds the custom URI scheme to `Info.plist`.
+
+Mach does not choose the application's Dart router. Handle the incoming URI in
+the routing package already used by the app (for example `go_router` or
+`app_links`). `mach deeplink verify` checks the Android manifest, associated
+domain, Xcode entitlement connection, generated association files, and optional
+live endpoints.
+
 ## Verify
 
 Verify local files:
@@ -191,6 +206,9 @@ Live verification checks:
 - `https://<domain>/apple-app-site-association`
 - `https://<domain>/.well-known/assetlinks.json`
 
-## Current Scope
+## Safety
 
-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.
+Expo configuration uses its plugin contract. Flutter native edits are applied
+only when Mach can identify standard launcher/Runner structures. Vanilla React
+Native verification remains conservative and reports native gaps rather than
+rewriting an unfamiliar project.

package/docs/frameworks/README.md

@@ -1,6 +1,9 @@
 # Framework Guides
 
-Mach uses `mach.config.json` as the source of truth for framework behavior. Builds do not infer framework from `package.json`, because package scanning is fragile in real projects and can make Expo, bare React Native, and future Flutter support affect each other accidentally.
+Mach uses `mach.config.json` as the source of truth for framework behavior.
+Builds do not infer framework at execution time because package or workspace
+scanning is fragile and can make Expo, bare React Native, and Flutter pipelines
+affect each other accidentally.
 
 ## Choose Your Framework
 
@@ -10,7 +13,7 @@ Mach uses `mach.config.json` as the source of truth for framework behavior. Buil
 | An Expo app that should run `expo prebuild` during cloud builds | `"expo"` | [Expo](expo.md) |
 | A Flutter app | `"flutter"` | [Flutter](flutter.md) |
 
-`mach init` and `mach link` create:
+`mach init` and `mach link` detect the selected application and create:
 
 ```json
 {
@@ -18,7 +21,8 @@ Mach uses `mach.config.json` as the source of truth for framework behavior. Buil
 }
 ```
 
-Change this to `"expo"` before building an Expo project. Flutter is accepted in config for forward compatibility, but Flutter builds intentionally fail until the Flutter builder is implemented.
+The value is `"flutter"` for a Flutter app and `"expo"` for an Expo app. Builds
+still use this explicit saved value; detection is only an initialization aid.
 
 ## Why This Is Explicit
 
@@ -26,7 +30,7 @@ The same repository can contain Expo packages, React Native native folders, cust
 
 - React Native builds never run Expo prebuild.
 - Expo builds keep the existing Expo prebuild and dev-client behavior.
-- Flutter can be added later without changing `mach build` commands.
+- Flutter runs its Dart/native pipeline without entering JavaScript tooling.
 - Documentation, CI, and support conversations can point to one clear setting.
 
 ## Required Config
@@ -61,10 +65,10 @@ repository root and set an explicit app directory:
 }
 ```
 
-Use the same `appDirectory` with `"react-native"` for a bare React Native app.
-Mach installs workspace dependencies from the repository root and runs
-framework-native commands from the selected app. If `appDirectory` is omitted,
-it defaults to `"."`, preserving existing root-level behavior.
+Use the same `appDirectory` with `"react-native"` for bare React Native or
+`"flutter"` for an application in a Dart pub workspace. Mach resolves workspace
+dependencies and runs framework-native commands from the selected app. If
+`appDirectory` is omitted, it defaults to `"."`, preserving existing behavior.
 
 Aliases such as `reactnative` and `react_native` are normalized to `react-native`, but new projects should use the canonical `react-native` value.
 
@@ -85,6 +89,6 @@ Framework selection only changes what happens inside the build runner.
 
 ## Failure Messages
 
-If `framework` is missing, Mach stops before queuing the build and asks you to add one of the allowed values. If `framework` is invalid, Mach stops before upload and prints the accepted values. If `framework` is `flutter`, Mach currently stops with a clear "Flutter builds are not implemented yet" message.
+If `framework` is missing, Mach stops before queuing the build and asks you to add one of the allowed values. If `framework` is invalid, Mach stops before upload and prints the accepted values. Framework-specific commands validate their capability before changing the project.
 
 This is intentional. A build should fail early and clearly instead of silently running the wrong native pipeline.

package/docs/frameworks/flutter.md

@@ -1,16 +1,21 @@
 # Flutter Builds
 
-Flutter is reserved in Mach configuration so the CLI can support it without changing user-facing commands later.
+Mach builds standalone Flutter applications on Android, iOS, and web while keeping
+the same build, credential, submission, versioning, and dashboard workflow used
+by React Native and Expo projects.
 
-## Current Status
+## Initialize or link
 
-`framework: "flutter"` is recognized as a valid config value, but Flutter cloud builders are not implemented yet. If you run a build with Flutter selected, Mach fails with a clear message instead of trying to run the React Native or Expo pipeline.
-
-## Planned Config Shape
+Run `mach init` in a Flutter application or at a Dart workspace root. Mach
+detects the app, writes `framework: "flutter"`, stores `appDirectory`, and pins
+the installed stable Flutter SDK for repeatable managed builds. `mach link`
+preserves every existing build profile and custom field.
 
 ```json
 {
   "framework": "flutter",
+  "appDirectory": ".",
+  "flutter": { "sdkVersion": "3.35.2" },
   "ios": {
     "bundleIdentifier": "com.example.app",
     "buildNumber": "auto"
@@ -18,50 +23,133 @@ Flutter is reserved in Mach configuration so the CLI can support it without chan
   "android": {
     "package": "com.example.app",
     "versionCode": "auto"
+  },
+  "build": {
+    "qa-blue": {
+      "environment": "qa",
+      "distribution": "internal",
+      "flutter": {
+        "flavor": "staging",
+        "target": "lib/main_staging.dart",
+        "mode": "release",
+        "dartDefinesFromEnv": ["API_URL", "APP_ENV"]
+      }
+    },
+    "customer-release": {
+      "environment": "production",
+      "distribution": "store",
+      "android": { "package": "com.example.app" },
+      "ios": { "bundleIdentifier": "com.example.app" },
+      "flutter": {
+        "flavor": "production",
+        "target": "lib/main_production.dart",
+        "obfuscate": true,
+        "splitDebugInfo": true
+      }
+    }
   }
 }
 ```
 
-## Planned Behavior
+Profile names are labels. They may be any unique strings, and Mach does not
+limit how many profiles exist. `environment`, `distribution`, platform fields,
+and the nested `flutter` object determine the build behavior.
+
+## Flutter profile fields
 
-The Flutter builder should be separate from the React Native and Expo builders:
+| Field | Purpose |
+| --- | --- |
+| `flavor` | Android product flavor and shared iOS scheme. Omit for unflavored apps. |
+| `target` | Dart entrypoint relative to `appDirectory`; defaults to `lib/main.dart`. |
+| `mode` | `debug`, `profile`, or `release`. Store/internal builds default to release. |
+| `dartDefinesFromEnv` | Names of selected environment values compiled with `--dart-define`. |
+| `obfuscate` | Obfuscates Android/iOS release Dart code and automatically preserves split debug symbols. |
+| `splitDebugInfo` | Preserves split debug symbols for Android/iOS releases even without obfuscation. |
 
-- Android should run Flutter/Gradle commands from the Flutter project.
-- iOS should run Flutter build/archive commands and then the same managed signing/upload flow.
-- Expo prebuild and React Native Metro cache handling should not run for Flutter.
-- Store submission should keep using the same `mach submit` command surface.
+These fields normally apply to both platforms. Put a nested `flutter` object
+under `android` or `ios` when native flavor/scheme names differ; platform fields
+override the shared values. For example, `android.flutter.flavor` can select an
+Android-only product flavor without requiring a matching Xcode scheme.
 
-Until that builder exists, use `react-native` or `expo`.
+Values named in `dartDefinesFromEnv` must exist in the resolved Mach environment.
+They are compiled into the application and therefore must not be treated as
+secrets. Mach stores only their names in build configuration, never the values.
 
-## Why It Is Already In Config
+Flutter's `default-flavor` in `pubspec.yaml` is honored when a profile does not
+set a flavor. For iOS flavors, Mach selects the shared scheme and matching
+`Debug-<flavor>`, `Profile-<flavor>`, or `Release-<flavor>` configuration. Set
+`build.<profile>.ios.iosConfiguration` explicitly for a nonstandard Xcode setup.
+For Android projects that declare product flavors without a default, Mach stops
+before allocating a cloud runner and identifies the missing profile field.
 
-Mach accepts `flutter` now so projects, Dashboard records, and docs can move toward a framework-neutral model before Flutter execution is enabled. This avoids another command change later. The command remains:
+## Commands
 
 ```bash
-mach build --platform ios --profile production
-mach build --platform android --profile production
+mach start --profile qa-blue
+mach build --platform android --profile qa-blue
+mach build --platform ios --profile customer-release
+mach build --platform web --profile customer-release
+mach audit
+mach credentials
+mach submit --latest --platform android --profile customer-release
+mach submit --latest --platform ios --profile customer-release
 ```
 
-Only the internal build runner changes once Flutter is implemented.
+Android store builds produce AAB files; internal/development builds produce APK
+files by default. Set `apk: true` or `apk: false` explicitly on any profile to
+choose APK or AAB. iOS reuses Mach's
+managed certificate, provisioning-profile, archive, validation, and submission
+pipeline. Automatic version counters become Flutter `--build-number` values and
+are verified in the final APK/AAB/IPA.
 
-## Current Failure Mode
+Web builds run `flutter build web` on the managed Linux runner and produce a
+downloadable `flutter-web.zip`. A Flutter `web/` directory is required. Web is
+not a store-submission or Maestro target, and it does not accept mobile-only
+obfuscation/split-debug-info flags.
 
-If you run a build today with:
+For Android/iOS release hardening, configure `flutter.obfuscate` or pass
+`--flutter-obfuscate`. Mach stores symbols outside the packaged app and exposes
+`flutter-symbols.zip` with the build artifacts so crash stacks can be decoded.
 
-```json
-{
-  "framework": "flutter"
-}
-```
+## Managed runner behavior
+
+- The exact configured Flutter SDK is activated or resolved from Flutter's
+  official archive manifest, downloaded, and SHA-256 verified.
+- Pub, Gradle, CocoaPods, and Xcode caches are isolated by project/framework/SDK.
+- Metro, Expo prebuild, Node dependency installation, and React Native cache
+  cleanup never run for Flutter.
+- Android signing material is written only to a temporary keystore and removed.
+- iOS signing material remains in Mach's temporary-keychain workflow.
+- `preBuild` and `postBuild` remain available to every profile.
 
-Mach stops before starting the React Native or Expo build pipeline and prints that Flutter builds are not implemented yet. This is safer than trying to run Gradle or Xcode with React Native assumptions.
+`mach audit` checks the SDK pin, Dart constraint, `flutter doctor`, static
+analysis, dependency advisories/freshness, native permissions, Android manifest,
+iOS ATS, source secrets, insecure storage, debug prints, and delivery impact.
 
-## Implementation Checklist
+## Delivery services
 
-When Flutter support is added, keep it isolated:
+```bash
+mach push setup --profile <profile>
+mach deeplink setup
+mach deeplink verify
+mach ota setup --profile <profile>
+mach ota release --platform all --profile <profile>
+mach ota publish --platform all --profile <profile> --track <track>
+```
 
-- Add Flutter-specific Android and iOS build runners.
-- Keep Expo prebuild logic out of Flutter.
-- Keep React Native Metro and bundling assumptions out of Flutter.
-- Reuse Mach credentials, signing, artifact upload, build pages, and submission flows.
-- Keep `mach build`, `mach submit`, and Dashboard UX unchanged.
+Push setup installs `mach_push_flutter`, creates an application-owned callback
+file, starts registration without blocking `runApp`, and wires APNs/Firebase
+native configuration. It follows `appDirectory` and wires every distinct Dart
+entrypoint selected by the profile's shared, Android, or iOS Flutter settings.
+Profile names are never special: use any name defined under `build.profiles`.
+Deep-link setup patches Android App Links, iOS Associated
+Domains, and the custom URI scheme idempotently. Flutter OTA delegates to the
+customer's Shorebird account; Mach never stores the provider token.
+
+## Current scope
+
+Mach supports standalone Flutter apps, including Dart workspaces with an
+explicit `appDirectory`. Flutter add-to-app modules remain intentionally out of
+scope because their host application requires a different build contract.
+`mach sitemap` remains Expo Router-specific and fails early for Flutter. Flutter
+web is a build artifact workflow; Mach does not host the generated website.

package/docs/ota.md

@@ -1,6 +1,6 @@
 # Mach OTA Updates
 
-Mach OTA publishes JavaScript bundles and assets through Mach API and Mach-managed object storage. It does not publish releases to EAS Update, and mobile apps never receive storage credentials.
+Mach OTA selects a safe provider by framework. Expo and bare React Native publish JavaScript/assets through Mach-managed storage. Flutter delegates Dart code push directly to the customer's Shorebird account, and Mach never receives or stores the Shorebird token.
 
 ## Supported apps
 
@@ -10,9 +10,35 @@ Mach currently uses the open-source `expo-updates` runtime for both supported Re
 | --- | --- | --- |
 | `expo` | Expo prebuild/CNG | Installs `expo-updates` and applies `@radhya/mach/expo-plugin` during prebuild. |
 | `react-native` | Committed `ios/` and `android/` projects | Installs Expo Modules when needed, installs `expo-updates`, and synchronizes its native configuration without running prebuild. |
+| `flutter` | Flutter Android/iOS applications | Initializes and orchestrates Shorebird using the customer-owned account and `SHOREBIRD_TOKEN` from the local/CI environment. |
 
 `mach-react-native` is reserved for a future Mach-owned client and is not a supported engine yet.
 
+## Flutter with Shorebird
+
+```bash
+mach ota setup --profile staging
+mach ota verify --profile staging
+mach ota release --platform all --profile staging
+mach ota publish --platform all --profile staging --track staging --release-version latest
+mach ota list --release-version 1.2.0+42
+mach ota promote --release-version 1.2.0+42 --patch-number 1
+mach ota rollback --release-version 1.2.0+42 --patch-number 2
+```
+
+Setup runs `shorebird init` when needed and stores only `enabled`,
+`engine: "shorebird"`, and the default track in `mach.config.json`. It never
+writes `SHOREBIRD_TOKEN`; interactive machines can use an existing Shorebird
+login, while CI should create an API key in Shorebird Console → Account → API
+Keys and provide it through the secret store. Release
+commands pin `flutter.sdkVersion` and reuse each profile's flavor, target, and
+selected `dartDefinesFromEnv`. Patch commands target the exact Shorebird release
+and can publish to `staging` before promotion to `stable`.
+
+Shorebird patches cannot safely carry native configuration changes or newly
+declared assets. Make a new `mach ota release` and store submission for those
+changes. Flutter web does not use mobile OTA.
+
 ## Initial setup
 
 Run setup from the project root:
@@ -22,7 +48,7 @@ mach ota setup
 mach ota verify
 ```
 
-Setup reads project ID, framework, channel, runtime policy, and existing URL from `mach.config.json`. Command flags have higher precedence. It also refreshes an older project-local `@radhya/mach` package so Expo prebuild uses a plugin compatible with the running CLI. Interactive setup asks before installing dependencies; use `mach --yes ota setup` in automation. Use `--skip-install` only when dependencies are managed separately.
+For Expo/React Native, setup reads project ID, framework, channel, runtime policy, and existing URL from `mach.config.json`. Command flags have higher precedence. It also refreshes an older project-local `@radhya/mach` package so Expo prebuild uses a plugin compatible with the running CLI. Interactive setup asks before installing dependencies; use `mach --yes ota setup` in automation. Use `--skip-install` only when dependencies are managed separately.
 
 For a bare React Native project, setup may make these intentional changes:
 

package/docs/push.md

@@ -13,7 +13,7 @@ mach link
 mach push setup
 ```
 
-`push setup` detects Expo or bare React Native; reads the native app
+`push setup` detects Flutter, Expo, or bare React Native; reads the native app
 identifiers; creates or reuses the matching MACH Push app; installs the mobile
 SDK; and starts permission, registration, and notification listeners from the
 application entry point.
@@ -35,6 +35,17 @@ the APNs entitlement, Android notification permission, Firebase config path,
 and public MACH Push configuration during prebuild. Expo Go cannot load custom
 native modules, so create a new development or production build after setup.
 
+Flutter setup installs `mach_push_flutter`, writes generated public config to
+`lib/mach_push.generated.dart`, and creates `lib/mach_push.dart` for callbacks.
+The callback file belongs to the application and is never overwritten. Mach
+imports it and adds one non-blocking startup call to the selected `main*.dart`
+entrypoint, re-registers rotated provider tokens, and applies the same APNs and
+Firebase native wiring used by bare React Native. If a custom entrypoint cannot
+be patched safely, setup prints the single startup call to add manually.
+Use `mach push setup --profile <profile>` when Flutter targets differ by build
+profile. Mach follows `appDirectory` and wires all distinct shared, Android,
+and iOS entrypoints selected by that profile; the profile may have any name.
+
 Use `mach push init` only when you intentionally want to create the server-side
 push app without installing or wiring a mobile SDK.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@radhya/mach",
-  "version": "2.4.4",
-  "description": "Mach CLI: Cloud Build Orchestrator for React Native & Expo",
+  "version": "2.6.0",
+  "description": "Mach CLI: cloud build and delivery for Flutter, React Native, and Expo",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsup src/index.ts src/commands/isolated-upload.ts --format esm --clean --minify --dts",
-    "test": "npm run typecheck:ota && tsx --test src/**/*.test.ts && node --test tests/*.test.cjs",
+    "test": "npm run typecheck:ota && node --import tsx --test \"src/**/*.test.ts\" && node --test tests/*.test.cjs",
     "typecheck:ota": "tsc --noEmit --skipLibCheck --moduleResolution Bundler --module ESNext --target ES2022 --esModuleInterop --noImplicitAny false src/commands/ota.ts",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
@@ -29,6 +29,7 @@
   "keywords": [
     "react-native",
     "expo",
+    "flutter",
     "build",
     "cloud",
     "ios",

package/dist/chunk-LO6DP2SE.js

@@ -1,4 +0,0 @@
-var o={name:"Mach",nameLower:"mach",nameUpper:"MACH",company:"Radhya Softlabs",npmScope:"@radhya",configFileName:"mach.config.json",configDir:".mach",workspacesDir:".mach-workspaces",remoteWorkspacesDir:"mach_workspaces",envPrefix:"MACH_",bucketPrefix:"skye-builds-385229479322",buildPrefix:"mach-build",credentialsKeychain:"mach-credentials.keychain",keychainPassword:"mach",cliTag:e=>` Mach CLI - ${e} `,fastlanePrefix:"mach",jsonStartMarker:"___MACH_JSON_START___",jsonEndMarker:"___MACH_JSON_END___",prewarmedMarker:"/opt/mach-prewarmed"};import s from"fs";import f from"path";import v from"os";import T from"axios";var m=f.join(v.homedir(),o.configDir),d=f.join(m,"credentials.json");function h(){return process.env[`${o.envPrefix}TOKEN`]?.trim()||void 0}function g(e){s.existsSync(m)||s.mkdirSync(m,{recursive:!0}),s.writeFileSync(d,JSON.stringify(e,null,2))}function l(){let e=h();if(e)return{token:e,email:"token-auth"};if(!s.existsSync(d))return null;try{return JSON.parse(s.readFileSync(d,"utf-8"))}catch{return null}}function I(){return s.existsSync(d)?(s.unlinkSync(d),!0):!1}function $(){let e=h();if(e)return{token:e,email:"token-auth"};let r=l();if(r?.token)return r;console.error(`\x1B[31mAuthentication required.\x1B[0m Either:
-  1. Run \x1B[33m${o.nameLower} login\x1B[0m for interactive login
-  2. Set \x1B[33m${o.envPrefix}TOKEN\x1B[0m environment variable for CI/CD`),process.exit(1)}async function k(e){let r=l();if(!r||!r.refreshToken)return null;try{let t=await T.post(`${e}/refresh-token`,{username:r.email,refreshToken:r.refreshToken});if(t.data.status==="success"&&t.data.user){let n={...r,id:t.data.user.id||r.id,token:t.data.user.token,refreshToken:t.data.user.refreshToken||r.refreshToken};return g(n),n.token}}catch{}return null}import S from"axios";import C from"dotenv";import x from"path";import{fileURLToPath as b}from"url";var _=x.dirname(b(import.meta.url));C.config({path:x.join(_,"../.env")});var c=process.env[`${o.envPrefix}API_URL`]||"https://mach-api.securejs.in",D="https://getmach.dev",A=c.includes("localhost:3001")||c.includes("127.0.0.1:3001")?c.replace("3001","8081"):D,B=process.env[`${o.envPrefix}DASHBOARD_URL`]||A;var u=S.create({baseURL:c,headers:{Connection:"close"}});u.interceptors.request.use(e=>{let t=l()?.token||process.env[`${o.envPrefix}TOKEN`];return t&&(e.headers.Authorization=`Bearer ${t}`),e},e=>Promise.reject(e));u.interceptors.response.use(e=>e,async e=>{let{config:r}=e;if((!e.response||e.code==="ECONNRESET"||e.code==="ETIMEDOUT")&&(!r._retryCount||r._retryCount<3)){r._retryCount=(r._retryCount||0)+1;let n=Math.pow(2,r._retryCount-1)*1e3;return console.warn(`\x1B[33m[NETWORK] Transient error (${e.code||"UNKNOWN"}). Retrying in ${n/1e3}s... (Attempt ${r._retryCount}/3)\x1B[0m`),await new Promise(a=>setTimeout(a,n)),u(r)}return Promise.reject(e)});u.interceptors.response.use(e=>e,async e=>{let r=e.config;if(e.response?.status===401&&!r._retry){if(r._retry=!0,process.env[`${o.envPrefix}TOKEN`])return console.error(`\x1B[31mAuthentication failed.\x1B[0m Your ${o.envPrefix}TOKEN may be invalid or expired.
-Generate a new token at the ${o.name} Dashboard \u2192 Settings \u2192 Access Tokens.`),Promise.reject(e);try{let n=await k(c);if(n)return r.headers.Authorization=`Bearer ${n}`,u(r)}catch(n){return Promise.reject(n)}}return Promise.reject(e)});var p=e=>String(e||"").trim().toLowerCase().replace(/_/g,"-");function y(e){let r=p(e);if(["development","dev"].includes(r))return"development";if(["adhoc","ad-hoc","internal","staging","stage","preview"].includes(r))return"adhoc";if(["store","app-store","appstore","production","prod"].includes(r))return"store"}function X(e){if(e.storedDistributionType!==e.requestedDistributionType)throw new Error(`Dashboard stored ${e.credentialType} as ${String(e.storedDistributionType||"unknown")} instead of ${e.requestedDistributionType}.`)}function Z(e){let r=y(e.requestedCredentialType);if(r)return r;let t=e.profile||{};if(t.developmentClient||t.simulator||t.ios?.simulator)return"development";let n=p(t.distribution),a=p(t.iosExportMethod||t.ios?.exportMethod),i=p(t.environment);return a==="app-store"||n==="store"?"store":a==="development"||n==="development"?"development":a==="ad-hoc"||a==="adhoc"||n==="ad-hoc"||n==="adhoc"||n==="internal"?"adhoc":i==="production"||i==="store"?"store":i==="development"||i==="dev"?"development":i==="staging"||i==="stage"||i==="preview"?"adhoc":y(e.buildProfile)||"development"}export{o as a,g as b,l as c,I as d,$ as e,c as f,B as g,u as h,y as i,X as j,Z as k};