@_nazmiforreal/flutter-ota 0.1.27 → 0.1.29

package/README.md

@@ -1,37 +1,131 @@
-# flutter-ota (flutter-ota CLI)
+# flutter-ota
 
-Command-line interface for [flutter_ota_kit](https://github.com/HYPER12755/flutter-ota-kit) — a multi-backend OTA ("code push") toolkit for Flutter Android, hot-updater compatible.
+[![npm](https://img.shields.io/npm/v/@_nazmiforreal/flutter-ota.svg)](https://www.npmjs.com/package/@_nazmiforreal/flutter-ota)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/HYPER12755/flutter-ota-kit/blob/main/LICENSE)
+
+### The command line for [flutter_ota_kit](https://pub.dev/packages/flutter_ota_kit) — build patches, deploy them to your backend, and manage rollouts.
+
+`flutter-ota` is the companion CLI for **flutter_ota_kit**, open-source OTA code
+push for Flutter Android. Pack a release APK into a signed patch, upload it to
+the backend **you** own (Supabase / Postgres / Cloudflare / AWS / PocketBase),
+and manage channels, staged rollouts, and instant rollback — no store review, no
+monthly bill.
+
+> The runtime SDK your app depends on is the separate
+> [`flutter_ota_kit`](https://pub.dev/packages/flutter_ota_kit) pub package.
+
+---
 
 ## Install
 
 ```bash
 npm i -g @_nazmiforreal/flutter-ota
+flutter-ota --help
+```
+
+A prebuilt `linux-x64` binary ships in the package. On other platforms the CLI
+compiles from bundled Dart source on first install, which needs the
+[**Flutter SDK**](https://flutter.dev) (the CLI shares the `flutter_ota_kit`
+Flutter package). If Flutter isn't available, build a binary once yourself:
+
+```bash
+cd $(npm root -g)/@_nazmiforreal/flutter-ota/dart-src/packages/cli-tools
+flutter pub get && dart compile exe bin/flutter_ota_kit.dart -o ../../bin/flutter-ota-<os>-<arch>
 ```
 
-This installs the `flutter-ota` command. A prebuilt Linux binary ships with the package; on other platforms it falls back to `dart compile exe` (requires the [Dart SDK](https://dart.dev)).
+---
 
-## Usage
+## The 60-second workflow
 
 ```bash
-flutter-ota --help
-flutter-ota keys                                              # generate an Ed25519 keypair
-flutter-ota build -a app-release.apk \
-  --version 1.0.0 --target-version-code 1                        # -> dist/patch.zip (all ABIs)
-flutter-ota deploy --source dist \
-  --channel production --backend supabase \
-  --key <PRIVATE_KEY_BASE64>                                      # upload + sign a bundle
+# 1. Scaffold config + a setup helper for your backend
+#    (adds the latest flutter_ota_kit to your pubspec automatically)
+flutter-ota init supabase        # or: postgres | cloudflare | aws | pocketbase
+
+# 2. Provision the backend (Supabase & PocketBase are fully automated)
+flutter-ota migrate supabase
+
+# 3. Build the release APK, then pack it into a device-ready patch
+flutter build apk --release
+flutter-ota build \
+  --apk build/app/outputs/flutter-apk/app-release.apk \
+  --version 1.0.1 \
+  --target-version-code 100
+
+# 4. Sign + deploy it to a channel
+flutter-ota deploy --source dist --channel production \
+  --target-app-version 1.0.0 --force -m "hotfix: crash on login"
+```
+
+Devices pick up the patch on their next launch. Pull it back with:
+
+```bash
+flutter-ota rollback --channel production
+```
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `init <backend>` | Scaffold config, `.env`, and `lib/flutter_ota_kit_setup.dart`; add the SDK dependency + `INTERNET` permission |
+| `build` | Pack a release APK into `dist/patch.zip` (all ABIs by default) |
+| `deploy` | Upload + register a bundle; sign it with `--key` |
+| `bundle` | `list` / `show` / `delete` / `disable` / `enable` / `force` / `promote` / `update` |
+| `channel` | `list` / `get` / `set` the live bundle per channel |
+| `rollback` | Disable the latest enabled bundle (or roll back to a specific one) |
+| `storage` | `list` / `delete` stored bundle objects |
+| `migrate` | Provision the backend schema |
+| `keys` | Generate an Ed25519 signing keypair |
+| `fingerprint` | Compute a deterministic build fingerprint |
+| `doctor` | Diagnose the environment + backend connectivity |
+| `config` | `get` / `set` / `list` config values |
+| `console` | Open the web console |
+| `pocketbase` | Manage a local single-binary PocketBase backend |
+
+Help works at every level, including nested subcommands:
+
+```bash
+flutter-ota deploy --help
+flutter-ota bundle list --help
+flutter-ota pocketbase records list --help
 ```
 
-### Backends
+---
+
+## Backends
+
+Select one with `--backend supabase|postgres|cloudflare|aws|pocketbase` (or set
+`provider` in `.flutter_ota_kit/config.json`). Settings resolve with a clear
+precedence:
+
+```
+explicit flag  >  environment variable  >  .flutter_ota_kit/config.json  >  default
+```
+
+Config search order: `./.flutter_ota_kit/config.json`, then
+`~/.flutter_ota_kit/config.json`. Secrets belong in your shell env or `.env`,
+never in committed config.
+
+| Backend | Provisioning |
+|---------|--------------|
+| **Supabase** | `migrate supabase` — SQL + storage bucket, fully automated |
+| **PocketBase** | `pocketbase install` + `pocketbase serve` — single binary, schema auto-installed |
+| **Postgres** | `migrate postgres` applies SQL migrations |
+| **Cloudflare** | `migrate cloudflare` creates D1 + R2, runs SQL |
+| **AWS** | No SQL — S3 bucket/prefix created on first `deploy` |
+
+---
 
-`--backend supabase|postgres|cloudflare|aws`.
-Each resolves its own env / `.flutter_ota_kit/config.json` (global: `~/.flutter_ota_kit/config.json`).
+## Documentation
 
-### Commands
+- [CLI Reference](https://github.com/HYPER12755/flutter-ota-kit/blob/main/doc/cli-reference.md)
+- [Getting Started](https://github.com/HYPER12755/flutter-ota-kit/blob/main/doc/getting-started.md)
+- [Backends](https://github.com/HYPER12755/flutter-ota-kit/blob/main/doc/backends.md)
+- [Production Playbook](https://github.com/HYPER12755/flutter-ota-kit/blob/main/doc/production-playbook.md)
 
-`init`, `build`, `deploy`, `bundle` (list/show/delete/disable/enable/force/promote/update),
-`rollback`, `channel` (list/get/set), `fingerprint`, `doctor`, `migrate`, `config`
-(get/set/list), `keys`, `console`, `storage` (list/delete).
+---
 
 ## License
 

package/dart-src/packages/cli-tools/README.md

@@ -1,5 +1,149 @@
 # flutter_ota_kit_cli
 
-Part of the [flutter_ota_kit](https://github.com/HYPER12755/flutter-ota-kit) OTA (over-the-air) update toolkit for Flutter Android.
+[![npm](https://img.shields.io/npm/v/@_nazmiforreal/flutter-ota.svg)](https://www.npmjs.com/package/@_nazmiforreal/flutter-ota)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
 
-See the project README for usage, backend setup, and the architecture overview.
+### The command line for [flutter_ota_kit](https://pub.dev/packages/flutter_ota_kit) — build patches, deploy them to your backend, and manage rollouts.
+
+`flutter-ota` is the companion CLI for **flutter_ota_kit**, open-source OTA code
+push for Flutter Android. It packs a release APK into a signed patch, uploads it
+to the backend **you** own (Supabase / Postgres / Cloudflare / AWS / PocketBase),
+and gives you first-class commands for channels, staged rollouts, and instant
+rollback.
+
+> This tool ships via npm as `@_nazmiforreal/flutter-ota`. The runtime SDK your
+> app depends on is the separate [`flutter_ota_kit`](https://pub.dev/packages/flutter_ota_kit)
+> pub package.
+
+---
+
+## Install
+
+```bash
+npm i -g @_nazmiforreal/flutter-ota
+flutter-ota --help
+```
+
+A prebuilt `linux-x64` binary ships in the package. On other platforms the CLI
+compiles from bundled Dart source on first install, which needs the
+[**Flutter SDK**](https://flutter.dev) (the CLI shares the `flutter_ota_kit`
+package). No Flutter? Point `flutter-ota` at a prebuilt binary you build once
+with `dart compile exe`.
+
+---
+
+## The 60-second workflow
+
+```bash
+# 1. Scaffold config + a setup helper for your backend (adds the latest
+#    flutter_ota_kit to your pubspec automatically)
+flutter-ota init supabase        # or: postgres | cloudflare | aws | pocketbase
+
+# 2. Provision the backend (Supabase & PocketBase are fully automated)
+flutter-ota migrate supabase
+
+# 3. Build the release APK, then pack it into a device-ready patch
+flutter build apk --release
+flutter-ota build \
+  --apk build/app/outputs/flutter-apk/app-release.apk \
+  --version 1.0.1 \
+  --target-version-code 100
+
+# 4. Sign + deploy it to a channel
+flutter-ota deploy --source dist --channel production \
+  --target-app-version 1.0.0 --force -m "hotfix: crash on login"
+```
+
+Devices pick up the patch on their next launch. To pull it back:
+
+```bash
+flutter-ota rollback --channel production
+```
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `init <backend>` | Scaffold `.flutter_ota_kit/config.json`, `.env`, and `lib/flutter_ota_kit_setup.dart`; add the SDK dependency + `INTERNET` permission |
+| `build` | Pack a release APK into a device-ready `dist/patch.zip` (all ABIs by default) |
+| `deploy` | Upload + register a bundle; sign it with `--key` |
+| `bundle` | `list` / `show` / `delete` / `disable` / `enable` / `force` / `promote` / `update` |
+| `channel` | `list` / `get` / `set` the live bundle per channel |
+| `rollback` | Disable the latest enabled bundle on a channel (or roll back to a specific one) |
+| `storage` | `list` / `delete` stored bundle objects |
+| `migrate` | Provision the backend schema (Supabase / Postgres / Cloudflare / AWS / PocketBase) |
+| `keys` | Generate an Ed25519 signing keypair |
+| `fingerprint` | Compute a deterministic build fingerprint for fingerprint-targeted rollouts |
+| `doctor` | Diagnose the environment + backend connectivity |
+| `config` | `get` / `set` / `list` config values |
+| `console` | Open the web console |
+| `pocketbase` | Manage a local single-binary PocketBase backend (install / serve / …) |
+
+Every command has help, including nested subcommands:
+
+```bash
+flutter-ota deploy --help
+flutter-ota bundle list --help
+flutter-ota pocketbase records list --help
+```
+
+Meaningful short flags map to the option's own name — e.g. on `deploy`:
+`-s`ource, `-c`hannel, `-m`essage, `-f`orce, `-t`arget-app-version,
+`-k`ey, `-b`ackend.
+
+---
+
+## Backends
+
+Select one with `--backend supabase|postgres|cloudflare|aws|pocketbase` (or set
+`provider` in `.flutter_ota_kit/config.json`). Each resolves settings with a
+clear precedence:
+
+```
+explicit flag  >  environment variable  >  .flutter_ota_kit/config.json  >  default
+```
+
+Config file search order: `./.flutter_ota_kit/config.json`, then the global
+`~/.flutter_ota_kit/config.json`. Secrets (service-role keys, DB passwords,
+tokens) belong in your shell environment or `.env` — never in committed config.
+
+| Backend | Provisioning |
+|---------|--------------|
+| **Supabase** | `migrate supabase` runs SQL + creates the storage bucket — fully automated |
+| **PocketBase** | `pocketbase install` + `pocketbase serve` — single binary, schema auto-installed |
+| **Postgres** | `migrate postgres` applies the SQL migrations |
+| **Cloudflare** | `migrate cloudflare` creates D1 + R2 and runs SQL |
+| **AWS** | No SQL — the S3 bucket/prefix is created on first `deploy` |
+
+See the [Backends guide](https://github.com/HYPER12755/flutter-ota-kit/blob/main/doc/backends.md)
+for per-backend env vars and setup.
+
+---
+
+## Signing
+
+```bash
+flutter-ota keys --save                 # generate a keypair, save the public half
+flutter-ota deploy --key <private-file> # sign the bundle (Ed25519 over the MD5)
+```
+
+Put the public key in your app via `FlutterPatcher.init(publicKeyBase64: '…')`;
+keep the private key on your CI/build machine, never in the app bundle.
+
+---
+
+## Documentation
+
+- [CLI Reference](https://github.com/HYPER12755/flutter-ota-kit/blob/main/doc/cli-reference.md) — every command + flag
+- [Getting Started](https://github.com/HYPER12755/flutter-ota-kit/blob/main/doc/getting-started.md)
+- [Backends](https://github.com/HYPER12755/flutter-ota-kit/blob/main/doc/backends.md)
+- [Configuration](https://github.com/HYPER12755/flutter-ota-kit/blob/main/doc/configuration.md)
+- [Production Playbook](https://github.com/HYPER12755/flutter-ota-kit/blob/main/doc/production-playbook.md)
+
+---
+
+## License
+
+MIT

package/dart-src/packages/cli-tools/lib/src/commands/init.dart

@@ -314,24 +314,52 @@ class InitCommand extends FlutterPatcherCommand {
       warn('pubspec.yaml not found; skipping dependency injection.');
       return;
     }
-    var content = pubspec.readAsStringSync();
+    final content = pubspec.readAsStringSync();
     if (content.contains(RegExp(r'^\s*flutter_ota_kit\s*:', multiLine: true))) {
       step('pubspec.yaml already references flutter_ota_kit');
       return;
     }
-    const dep = '  flutter_ota_kit: ^0.1.4\n';
+    // Prefer `flutter pub add`, which resolves the LATEST published version and
+    // writes a proper caret constraint — so the CLI never hardcodes (and never
+    // goes stale on) a version number.
+    final exe = _flutterOrDart();
+    if (exe != null) {
+      final res = Process.runSync(exe, ['pub', 'add', 'flutter_ota_kit']);
+      if (res.exitCode == 0) {
+        step('Added `flutter_ota_kit` (latest) via `$exe pub add`');
+        return;
+      }
+      warn('`$exe pub add flutter_ota_kit` failed; falling back to a manual '
+          'edit. Run it yourself if the constraint looks wrong.');
+    }
+    // Fallback: append an unpinned dependency so `pub get` picks the latest
+    // compatible release. Still no hardcoded version.
     final marker = '\ndependencies:';
     final idx = content.indexOf(marker);
     if (idx == -1) {
-      warn(
-        'Could not find a `dependencies:` block; add `flutter_ota_kit` manually.',
-      );
+      warn('Could not find a `dependencies:` block; add `flutter_ota_kit` '
+          'manually (run `flutter pub add flutter_ota_kit`).');
       return;
     }
     final insertAt = idx + marker.length;
-    content = content.replaceRange(insertAt, insertAt, '\n$dep');
-    pubspec.writeAsStringSync(content);
-    step('Added `flutter_ota_kit` dependency to pubspec.yaml');
+    final updated =
+        content.replaceRange(insertAt, insertAt, '\n  flutter_ota_kit: any\n');
+    pubspec.writeAsStringSync(updated);
+    step('Added `flutter_ota_kit` dependency to pubspec.yaml '
+        '(run `flutter pub get` to resolve the latest version)');
+  }
+
+  /// Resolve the `flutter` executable (preferred) or `dart` for `pub add`.
+  String? _flutterOrDart() {
+    for (final exe in const ['flutter', 'dart']) {
+      try {
+        final r = Process.runSync(exe, ['--version']);
+        if (r.exitCode == 0) return exe;
+      } catch (_) {
+        // not on PATH; try next
+      }
+    }
+    return null;
   }
 
   void _addInternetPermission() {

package/dart-src/packages/cli-tools/pubspec.yaml

@@ -22,7 +22,7 @@ dependencies:
   # merged `flutter_ota_kit` package under lib/src/pkg/. The CLI depends on the
   # single package instead of eight. NOTE: `flutter_ota_kit` is a Flutter plugin,
   # so building the CLI now requires the Flutter SDK (not just the Dart SDK).
-  flutter_ota_kit: ^0.2.0
+  flutter_ota_kit: ^0.2.2
   http: ^1.2.0
   shelf: ^1.4.0