@radhya/mach 2.6.3 → 2.6.4

package/README.md

@@ -2,7 +2,7 @@
 
 **Cloud Build & Delivery for React Native, Expo, and Flutter**
 
-Mach is a CLI that builds, signs, audits, versions, and submits Flutter, React Native, and Expo apps locally or in the cloud.
+Mach is a CLI that builds, signs, audits, versions, submits, and deploys static web releases for Flutter, React Native, and Expo apps locally or in the cloud.
 
 ## Installation
 
@@ -67,9 +67,121 @@ mach build --platform web # Flutter projects
 | `mach audit`               | Check project health, delivery impact, and security locally         |
 | `mach agent`               | Manage the local device discovery agent for Install Hub            |
 | `mach host`                | Set up S3 static hosting and CloudFront                            |
+| `mach web`                 | Deploy and manage static web releases through Mach Web Hosting     |
 | `mach sitemap`             | Generate sitemap.xml from Expo Router app routes                   |
 | `mach deeplink`            | Configure and verify universal links and Android App Links         |
 
+## Static Web Hosting
+
+`mach web` is Mach's managed static release workflow for Expo web, React Native
+Web, Flutter web, and any finished static site. It is deliberately separate
+from both `mach host` (the existing AWS S3 + CloudFront setup) and OTA updates.
+
+Build your app on a developer machine or in CI, then upload only its finished
+static directory. Each deployment receives an immutable preview URL. Mach
+aliases point to immutable releases, so a promotion or rollback never rebuilds
+or overwrites a previously published site.
+
+| Address | Example for `shop` |
+| --- | --- |
+| Production | `https://shop.getmach.dev` |
+| Staging | `https://shop--staging.getmach.dev` |
+| Immutable preview | `https://shop--d_<deployment-id>.getmach.dev` |
+
+Before the first web deployment, the project owner chooses the Production
+subdomain in **Dashboard → Web Hosting**. The project slug is the default. The
+name is reserved globally and locks after the first deployment so shared URLs
+remain permanent.
+
+### Reuse existing mobile profiles
+
+Do not rename mobile profiles to match a hostname. Add an explicit `web` block
+to the profiles you already use. It maps release intent to a web alias and tells
+Mach where the finished static output is written:
+
+```json
+{
+  "build": {
+    "qa-mobile": {
+      "distribution": "internal",
+      "web": { "alias": "staging", "output": "dist" }
+    },
+    "store-release": {
+      "distribution": "store",
+      "web": { "alias": "production", "output": "dist" }
+    }
+  }
+}
+```
+
+`web.alias` accepts `production` or `staging`; it defaults to `production`.
+`web.output` is the output folder, such as `dist` for Expo/React Native Web or
+`build/web` for Flutter. Mach does not infer an address from a profile name and
+does not inject mobile profile secrets into static browser files.
+
+### Deploy releases
+
+The output directory must have `index.html` at its root.
+
+```bash
+# Upload a finished Expo or React Native Web export
+mach web deploy --output dist
+
+# Run Expo export locally, then upload the result
+mach web deploy --build --profile store-release
+
+# Run flutter build web --release locally, then upload build/web
+mach web deploy --build --profile qa-mobile
+
+# Create an immutable review link without moving any alias
+mach web deploy --output build/web --alias staging --no-promote
+```
+
+Use the deployment ID to control aliases without another build:
+
+```bash
+mach web list
+mach web promote d_0123abcd --alias production
+mach web rollback --alias production
+mach web status
+```
+
+The dashboard Web Hosting page provides the same controls and shows the
+deployment's file count, size, profile, Git branch, commit, immutable preview,
+and active aliases. Web deployments also appear in Release History alongside
+native builds.
+
+### CI
+
+Install the CLI with a scoped `MACH_TOKEN`, then use the same committed profile
+mapping that developers use locally:
+
+```bash
+npm install -g @radhya/mach@latest
+mach web deploy --build --profile store-release --message "$GIT_COMMIT"
+```
+
+For pull requests, use `--no-promote`; promote the reviewed deployment in a
+protected release step. File uploads go directly from the CLI to private R2
+storage using short-lived signed URLs. The Mach API stores release metadata and
+does not proxy your static files.
+
+### Scope and customer domains
+
+Mach Web Hosting serves static assets and SPA navigation fallback. It does not
+deploy customer serverless functions, SSR, databases, or server code. A web app
+can call your normal API, but browser-visible values are public: keep database
+credentials and privileged secrets in a backend.
+
+The included `*.getmach.dev` project addresses are available immediately.
+Customer-owned domains are a Premium capability enabled only after Cloudflare
+SSL for SaaS is configured by the Mach operator. When enabled, customer domains
+always point to Production for now:
+
+```bash
+mach web domain add --domain www.customer.com
+```
+
 ## Managed Maestro Testing
 
 Mach's E2E testing layer is being implemented to run Maestro without requiring Maestro Cloud:
@@ -519,6 +631,8 @@ and continue to use `"."`.
 | `flutter.dartDefinesFromEnv` | Environment-key names passed with `--dart-define`. Values are compiled into the app and must not be secrets                              |
 | `flutter.obfuscate`      | Obfuscate Dart code for Android/iOS release builds and retain downloadable split debug symbols                                                |
 | `flutter.splitDebugInfo` | Retain downloadable split debug symbols without otherwise changing app behavior                                                               |
+| `web.alias`              | Web release alias for this profile: `production` or `staging`; defaults to `production`                                                       |
+| `web.output`             | Finished static output directory for `mach web deploy`, such as `dist` or `build/web`                                                         |
 | `preBuild` / `postBuild` | Shell command or script reference to run around the build                                                                                      |
 | `envGroups`              | Array of environment group names to merge into this profile                                                                                    |