The Garage SDKs, in the open

garage_auth, garage_entitlements, garage_iap and garage_ui, moved out of
Garage-Services and Metro-Map-Maker into one public repo. MIT, one readme,
docs under docs/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013F4NWNvYcdeSgqbWMT1VQ7

docs/local-development.md

@@ -0,0 +1,146 @@
+# Local development
+
+How to edit the SDKs and an app at the same time, and see the change in the
+running app straight away — no push, no tag, no `ref:` bump while you iterate.
+
+
+## The setup
+
+Your app keeps depending on the SDKs the normal way, as pinned git deps (see
+[Install](../README.md#install)):
+
+```yaml
+dependencies:
+  garage_ui:
+    git:
+      url: https://git.imbenji.dev/IMBENJI.NET/Garage-SDKs.git
+      path: garage_ui
+      ref: v0.1.0
+```
+
+Leave that alone. Clone this repo somewhere, then next to the app's
+`pubspec.yaml` add a `pubspec_overrides.yaml` that points the packages you're
+working on at the local checkout:
+
+```yaml
+# local garage sdks, so edits hot reload without a push. gitignored, never commit
+dependency_overrides:
+  garage_ui:
+    path: ../Garage-SDKs/garage_ui
+```
+
+The path is relative to the app's folder, so adjust it to wherever your checkout
+actually lives. If there's a space anywhere in it, quote it:
+
+```yaml
+    path: "../../Documents/Projects/Garage Services/SDKs/garage_ui"
+```
+
+pub reads `pubspec_overrides.yaml` on its own, you dont pass it anything. Run
+`flutter pub get` and you should see a line per override:
+
+```
+! garage_ui 0.1.0 from path ../Garage-SDKs/garage_ui (overridden in ./pubspec_overrides.yaml)
+```
+
+If that line isn't there, the override isn't active — check the path.
+
+
+## Overriding auth, entitlements or iap
+
+`garage_entitlements` and `garage_iap` both depend on `garage_auth` by path
+(`path: ../garage_auth` in their pubspecs). So the moment you override either
+one, the local copy pulls in a local `garage_auth` too — and your app is still
+asking for the git one. pub sees `garage_auth` from two sources and refuses.
+
+The rule: **if you override `garage_entitlements` or `garage_iap`, override
+`garage_auth` as well.**
+
+```yaml
+dependency_overrides:
+  garage_auth:
+    path: ../Garage-SDKs/garage_auth
+  garage_entitlements:
+    path: ../Garage-SDKs/garage_entitlements
+  garage_ui:
+    path: ../Garage-SDKs/garage_ui
+```
+
+`garage_ui` doesnt depend on any of the others, so it can be overridden on its
+own.
+
+
+## Hot reload
+
+- Changed `pubspec_overrides.yaml` (added, removed, or edited a path)? Run
+  `flutter pub get`, then do a full restart of the app. Hot reload wont pick up
+  a dependency swap.
+- After that, edits inside the SDK checkout behave like your own app code. Save
+  and hot reload.
+- Same caveats as app code: if the change is in something that only runs once
+  (`main()`, initial state, a `const` widget tree), hot restart instead.
+
+
+## Gitignore it
+
+Add this to the app's `.gitignore`:
+
+```
+pubspec_overrides.yaml
+```
+
+The path in it only exists on your machine. Commit it and every other checkout
+breaks, and so does any CI job or Docker image build, because none of them have
+your local SDK checkout sitting next to the app.
+
+While the override is active, `pubspec.lock` records the path source instead
+of the git one. Thats expected. Just dont ship a lockfile in that state — see
+below.
+
+Also: never edit the copies under `~/.pub-cache/git`. pub treats that folder as
+disposable and will overwrite or delete it without asking, and your app isn't
+necessarily even reading from the copy you changed. Edit a real checkout and
+override to it.
+
+
+## Shipping an SDK change
+
+Once the change works locally:
+
+1. Commit and push it in this repo.
+2. Tag a new version, e.g. `v0.1.1`, and push the tag.
+3. In each app that should get it, bump `ref:` to the new tag. Do it on purpose,
+   per app — dont float `main`.
+4. Check the app builds **without** the override. Move it aside, resolve against
+   the real tag, and analyze:
+
+   ```sh
+   mv pubspec_overrides.yaml pubspec_overrides.yaml.off
+   flutter pub get
+   flutter analyze
+   ```
+
+   This is the step that catches a forgotten push, a tag on the wrong commit, or
+   a `ref:` you missed. It also puts `pubspec.lock` back on the git source.
+5. Deploy, then move the override back if you're carrying on.
+
+
+## Running the SDKs' own tests
+
+These have tests:
+
+```sh
+cd garage_entitlements && flutter test
+cd garage_iap && flutter test
+cd garage_ui && flutter test
+```
+
+`garage_auth` has no `test/` dir yet.
+
+There are two examples, both minimal wiring references rather than full apps:
+
+- `garage_auth/example/main.dart` — a single file showing `GarageAuth` wired
+  into an app. It has no pubspec of its own.
+- `garage_iap/example` — a small package wiring `garage_auth` + `garage_iap`
+  together by path. `flutter pub get` and `flutter analyze` in there is a quick
+  way to check the two still fit together.