otaflow 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Otaflow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# otaflow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Over-the-air updates for Expo apps. Sign an update on your machine, publish it to a preview channel, promote it to production with an approval, and roll it back when something breaks. Your code-signing key never leaves your hands.
+
+This is the command line for [Otaflow](https://otaflow.com). You need an Otaflow account (accounts are opened by Otaflow during the partner period) and Node.js 22 or newer.
+
+```bash
+npx otaflow --help
+# or install it
+npm install --global otaflow
+```
+
+## Start
+
+```bash
+otaflow login                         # opens a browser page: confirm the code, allow
+otaflow apps create --name "My App" --slug my-app
+cd my-expo-project
+otaflow init --app my-app             # link the folder to the app
+otaflow keys init                     # make the code-signing key and register its public half
+```
+
+`keys init` writes the **certificate** to `./certs/certificate.pem` (commit it) and keeps the **private key** outside the project, in your user config folder. Back the key up: Otaflow cannot recover it, and without it no update reaches installed apps until a new build ships. Add what the command prints to your `app.json`:
+
+```json
+{
+  "expo": {
+    "updates": {
+      "url": "https://ota.otaflow.com/u/my-app/manifest",
+      "codeSigningCertificate": "./certs/certificate.pem",
+      "codeSigningMetadata": { "keyid": "main", "alg": "rsa-v1_5-sha256" }
+    },
+    "runtimeVersion": { "policy": "fingerprint" }
+  }
+}
+```
+
+Your project needs `expo-updates`. Build a release binary with this configuration once; updates reach it from then on.
+
+## Every day
+
+```bash
+git commit -am "Fix the checkout crash"
+otaflow publish -m "Fix the checkout crash"      # to preview: exports, signs, uploads what changed
+otaflow promote                                  # preview to production (the owner directly; others ask)
+otaflow promotions list                          # pending requests
+otaflow promotions approve --request <id>        # owner or manager
+otaflow rollback --channel production --previous # go back one update
+otaflow rollback --channel production --embedded # back to the JavaScript inside the binary
+otaflow pause --channel production               # stop devices getting updates, now
+otaflow resume --channel production
+otaflow list                                     # channels, heads, recent updates
+```
+
+`publish` refuses a dirty git tree and a commit that is already a channel's head, and refuses an update whose bundle contains values from your `.env` files.
+
+A rollback is a new update that carries an older update's content. Each publish also signs, ahead of time, the rollbacks that could undo it, so a manager can roll back from the dashboard or with `otaflow rollback --prepared` **without** the signing key.
+
+## In CI
+
+```bash
+export OTAFLOW_API_KEY=otk_...              # otaflow apikey create --app my-app --name CI --actions publish,request_promote
+export OTAFLOW_SIGNING_KEY="$(cat private-key.pem)"   # or OTAFLOW_SIGNING_KEY_PATH=/path/to/key.pem
+otaflow publish -m "$GITHUB_SHA"
+otaflow promote --wait
+```
+
+A key can publish to preview and ask for a promotion; it can never approve one. Approving needs a person.
+
+## Reference
+
+| Command | What it does |
+|---|---|
+| `login`, `whoami`, `logout` | Sign in through the browser, see who you are, forget the login |
+| `apps list`, `apps create` | List and create apps |
+| `init` | Link this folder to an app |
+| `keys init`, `keys register`, `keys list`, `keys public`, `keys revoke` | The code-signing key |
+| `apikey create`, `apikey list`, `apikey delete` | CI keys, scoped to an app and some actions |
+| `publish` | Export, sign and publish to a channel |
+| `promote`, `promotions list/approve/reject/cancel` | Move preview to production; decide requests |
+| `rollback` | `--previous`, `--to <id>`, `--embedded`, `--prepared` |
+| `pause`, `resume` | The brake on a channel |
+| `list` | Channel status |
+
+Every command takes `--json` for machine-readable output and `--api-url` (or `OTAFLOW_API_URL`) to point at another Otaflow address.
+
+Where the login is kept: the OS keychain when there is one, otherwise `~/.config/otaflow/credentials.json` with mode 0600. Set `OTAFLOW_CREDENTIALS=file` to force the file (containers, CI).
+
+## License
+
+MIT. See `LICENSE`.