Tony/683 migrate template app

.gitignore

@@ -10,7 +10,7 @@
 ARCHIVE
 ignore
 pubspec.yaml.*
-!templates/solidpod/pubspec.yaml.tmpl
+!templates/solidui/pubspec.yaml.tmpl
 
 qtest_*.txt
 

.pubignore

@@ -15,6 +15,8 @@ ARCHIVE
 ignore
 pubspec.yaml.*
 
+!templates/solidui/pubspec.yaml.tmpl
+
 .flutter-plugins*
 
 qtest_*.txt

README.md

@@ -181,13 +181,149 @@ SolidUI requires the following dependencies:
 
 ## Quick Start to Create an App
 
-To create a new Solid-based app using `solidui` named `myapp` and
-published by `example.com` begin with:
+`solidui` ships with an app template — a ready-to-run Pod file browser,
+complete with a navigation rail and a status bar, built on `solidui`. It is the
+practical equivalent of a `flutter create --template=solidui`, which stock
+Flutter cannot offer because the `--template` flag only accepts a fixed set of
+built-in types. We provide a small generator instead.
+
+The recommended way is to activate the generator once and then run it from any
+directory:
+
+```bash
+flutter pub global activate solidui
+solidui create my_pod_app
+```
+
+Alternatively, `dart run solidui:create` works **only from within a package
+that already depends on `solidui`** (for example a clone of the `solidui`
+repository), because `dart run` must resolve the `solidui:create` executable
+through that project's `pubspec.yaml`:
+
+```bash
+dart run solidui:create my_pod_app
+```
+
+Running `dart run solidui:create` from an unrelated directory fails with
+`Found no pubspec.yaml file in <folder> or parent directories` — use the global
+activation above instead.
+
+### Running from a local checkout (before publishing)
+
+If you are working on a branch of `solidui` that is not yet published to
+pub.dev, you can still generate an app from any directory without publishing.
+Replace `/path/to/solidui` below with the path to your local checkout.
+
+- Run the generator script directly. This always uses your current working tree
+  — both `bin/create.dart` and the template files — so it picks up your edits
+  on every run:
+
+  ```bash
+  dart run /path/to/solidui/bin/create.dart my_pod_app
+  ```
+
+- Or activate the local checkout and use the short `solidui create` command
+  anywhere:
+
+  ```bash
+  flutter pub global activate --source path /path/to/solidui
+  solidui create my_pod_app
+  ```
+
+  Note that this takes a snapshot of `bin/create.dart`, so re-run the
+  `activate` command after editing the generator itself; edits to the template
+  files are picked up without re-activating.
+
+For Windows users, command `solidui` can be added to the system by the
+following steps:
+
+- Run **PowerShell**
+- Run the following commands:
+
+  ```shell
+  $pubCacheBin = "$env:LOCALAPPDATA\Pub\Cache\bin"
+  $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+
+  if ($userPath -notlike "*$pubCacheBin*") {
+    [Environment]::SetEnvironmentVariable("Path", "$userPath;$pubCacheBin", "User")
+  }
+  ```
+
+- Close **Powershell**
+- Open **Command Prompter** or **PowerShell** and use `solidui` command.
+
+The generator runs `flutter create` to lay down the platform folders, overlays
+the template (substituting your app name), and runs `flutter pub get`. Useful
+options:
+
+| Option                | Description                                          |
+|-----------------------|------------------------------------------------------|
+| `--org <id>`          | Reverse-domain org id (default: `com.example`).      |
+| `--title <text>`      | Window title shown by the app.                       |
+| `--description <text>`| `pubspec` description.                               |
+| `-o, --output <dir>`  | Output directory (default: the app name).            |
+| `--no-flutter-create` | Render template only; skip platform folders.         |
+| `--no-pub-get`        | Skip the final `flutter pub get`.                    |
+
+The generated app starts at a `SolidLogin` screen and, once signed in, shows a
+`SolidScaffold` with a home page, an app-files browser and a whole-POD browser.
+
+### Enabling login (Solid-OIDC client registration)
+
+Before login will work you must publish a Client Identifier Document for the
+app. The generator writes a ready-to-deploy copy of it, together with the web
+redirect helper, into the generated project's `solid/` folder:
+
+- `solid/client-profile.jsonld` — the Solid-OIDC Client Identifier Document. Its
+  `redirect_uris` are generated to match, byte for byte, the `redirectUris`
+  passed to `SolidLogin` in `lib/app.dart`.
+- `solid/redirect.html` — the web and post-logout redirect helper used by the
+  `oidc` package.
+
+Two points are worth understanding:
+
+- `client-profile.jsonld` is **not** a file the app creates on your POD, and it
+  cannot be — the app is not yet authenticated at login time. It must already be
+  hosted, and be publicly readable, at the URL given as the `clientId`. During
+  login the identity provider fetches that URL to learn which `redirect_uris`
+  are permitted; if it is missing (HTTP 404) the provider refuses to hand
+  control back to the app after the consent screen, and login fails with an
+  `ASWebAuthenticationSession Code=1` (cancelled) error.
+- The POD data folders (for example `<appDir>/data` and `<appDir>/sharing`) are
+  created by solidpod's `generateDefaultFolders()` **after** a successful login.
+  If they have not appeared, it is because login has not completed — that is a
+  symptom of the missing client profile, not the cause.
+
+To enable login, publish both files at the location your `clientId` points to.
+If you maintain the Solid server — for example the Australian Solid Community
+(`solidcommunity.au`) — deploy them alongside the other apps exactly as
+`filepod` does:
+
+```console
+https://solidcommunity.au/apps/my_pod_app/client-profile.jsonld
+https://solidcommunity.au/apps/my_pod_app/redirect.html
+```
+
+Then confirm the document is reachable (a public `200`, requiring no
+authentication):
 
 ```bash
-flutter create --template solidui --domain com.example myapp
+curl -I https://solidcommunity.au/apps/my_pod_app/client-profile.jsonld
 ```
 
+Once it returns `200`, run `flutter run` and the login redirect will complete
+(`filepod`'s own document returns `200`, which is why it can sign in).
+Otherwise, host the two files at any public URL you control and update the
+`clientId` — and the matching `redirect.html` entry in `redirectUris` — in
+`lib/app.dart` accordingly. Note that only the custom redirect **scheme**
+(`<org>.<name-without-underscores>://redirect`, e.g. `com.example.mypodapp`)
+drops the underscores from the project name, because a URI scheme may not
+contain them; every other identifier keeps the project name as-is.
+
+After generating, also review the remaining placeholders — the `clientId`,
+`redirectUris` and `link` in `lib/app.dart`, and the constants in
+`lib/constants/app.dart` — and update them for your own deployment.
+
 A demonstrator example application (DemoPod) is available in the
 [example](example/) folder of this repository. DemoPod showcases the
 suite of functionality provided by `solidpod` and `solidui`,