@magmonium/one 0.4.19 → 0.4.21

package/assets/docs/en/app-repo.md

@@ -0,0 +1,296 @@
+# Linking an mm App to GitHub
+
+How an App's source gets into a GitHub repository, and how you and your
+collaborators keep working on it from the editor. Releasing what is in that
+repository is a separate step, covered in the release guide.
+
+## What the repository holds
+
+Each App has one repository: its **AppRepo**. It holds two things:
+
+| Path | What it is |
+| --- | --- |
+| `.magmonium/` | The design: Screens, Features, state, rules, nav and assets as you composed them. This is what the editor reads back. |
+| `src/app/custom/`, `mag_assets/` and the shell | What you wrote by hand and what the editor cannot regenerate: your own components, the app's assets, `package.json`, `angular.json`, the CI workflows. |
+
+The generated code — `src/app/features/`, `pages/`, `widgets/`, `shared/lib/`, `shared/type/` and the router and provide overlays — is **not** committed. `npm start`, `npm run build*` and `npm test` regenerate it from `.magmonium/` through `@magmonium/cli` (`npm run gen:code`), so a clone builds after `npm install`, without the editor. `.gitignore` excludes it.
+
+The Store records which repository belongs to which App. The repository's own
+files only carry the App's id, so moving the App to another repository leaves
+nothing stale behind.
+
+One repository serves one App. A repository already linked to another App is
+refused.
+
+## Linking, step by step
+
+Linking takes three steps. Steps 1 and 2 happen on GitHub, step 3 in
+Magmonium. Do them in this order: Magmonium checks the repository at the
+moment you link, so the GitHub side has to be ready first.
+
+| Step | Where | Who |
+| --- | --- | --- |
+| 1. Create the repository | GitHub | anyone who can create repositories there |
+| 2. Install the Magmonium GitHub App on it | GitHub | an admin of that repository |
+| 3. Link it to the App | Store or editor | the App's Owner |
+
+The person doing step 2 and the App's Owner are usually the same person, but
+they do not have to be. Magmonium never asks for your GitHub password or a
+GitHub token. The installation in step 2 is the only permission it uses.
+
+### Step 1 — Create the repository
+
+On GitHub, choose **New repository** under your account or an organization.
+
+- **Name it after the App.** Using the App link (for example `m-orders`)
+  keeps things easy to find, but any name works.
+- **Private or public.** Either works.
+- **Contents.** Leave it empty. Adding a `README.md`, `LICENSE` or
+  `.gitignore` is fine. Do not add a `package.json` or any app code: the first
+  Push writes the whole app for you.
+
+You can also reuse a repository that already holds a Magmonium design, that
+is, one with a `.magmonium/` folder on its default branch. Do this, for
+example, when you move an App to a new repository or restore one.
+
+A repository that holds anything else, such as a hand-written Angular app, is
+refused. It has no design for the editor to read, and the first Push would
+overwrite its files.
+
+### Step 2 — Install the Magmonium GitHub App
+
+This step is what proves to Magmonium that the repository is yours to hand
+over. GitHub only lets an admin of the repository install an app on it.
+
+1. Open the install page:
+   **[github.com/apps/magmonium/installations/new](https://github.com/apps/magmonium/installations/new)**.
+   The same link appears as **Install the Magmonium GitHub App** next to the
+   repository field when you link, and again if a link is refused.
+2. On GitHub, pick the **account or organization** that owns the repository.
+3. Choose **Only select repositories** and select the repository from step 1.
+   *All repositories* also works, but gives Magmonium access to more than it
+   needs.
+4. Press **Install**.
+
+**If the GitHub App is already installed on that account**, GitHub shows
+**Configure** instead of **Install**. Open it and add the new repository
+under *Repository access*. Then press **Save**.
+
+**For an organization repository**, an organization owner may need to install
+the app or approve your request. If GitHub says *request sent*, the link only
+works after an owner approves it.
+
+Magmonium uses the installation only to read and write the files of the
+repositories you selected, which is what Pull and Push need. Remove a
+repository from the installation, or uninstall the app, and Magmonium can no
+longer reach it.
+
+### Step 3 — Link it to the App
+
+Only the App's **Owner** can link. Collaborators see *Only the App's Owner can
+link its repository.*
+
+Enter the repository in any of these forms:
+
+```text
+https://github.com/acme/orders
+https://github.com/acme/orders.git
+git@github.com:acme/orders
+acme/orders
+```
+
+You can link from three places.
+
+#### When you create an App in the Store
+
+1. In the Store, start **Create App**.
+2. In the **Info** step, fill in **App Link**, **App Type** and
+   **Repository URL**. All three are required.
+3. Continue. Magmonium creates the App and links the repository in one go.
+   - **Link accepted:** the wizard moves on to **Deploy Setup** and then
+     **How to Publish**.
+   - **Link refused:** the App is **not** created. The wizard stays on
+     **Info**, shows the reason, and offers **Install the Magmonium GitHub
+     App**. Fix the problem, then continue again.
+
+While the App is still a draft, you can go back to **Info** and change the
+**Repository URL**. A changed URL is checked again, exactly like the first
+link.
+
+#### From the editor, for an App you already have
+
+1. In the editor's page menu, choose **Open App**.
+2. Pick the App. If it has no repository yet, the editor shows **Link
+   repository** with the install link and a **GitHub repository** field.
+3. Enter the repository and press **Link repository**.
+4. **Link accepted:** the editor moves on to choosing a **Branch** to Pull
+   (`dev` by default). Pulling a fresh repository gives you an **empty**
+   workspace named after the App, ready to compose in. It replaces whatever
+   the workspace held before, so if you already composed something you want
+   to keep, use the next path instead.
+
+#### From the editor, for a workspace with no App yet
+
+If you composed first and have no App yet:
+
+1. Choose **Open App**, then **Create App**. The editor offers this when the
+   workspace has Screens but no App.
+2. Fill in the name, **App link**, type, description and **GitHub
+   repository**. The link is prefilled from the app's name.
+3. Press **Create App**.
+   - **Link accepted:** the editor keeps your workspace, links it to the new
+     App, and goes straight to **Push**.
+   - **Link refused:** unlike the Store wizard, the App **is** created. The
+     editor shows the reason on the **Link repository** step, so you can fix
+     it and link again without creating a second App.
+
+### Check that it worked
+
+- In the Store, the App's deployment page shows the repository URL.
+- In the editor, **Open App** for that App now goes straight to choosing a
+  **Branch** instead of asking for a repository.
+- After your first Push, the repository on GitHub has a `dev` branch holding
+  `.magmonium/`, `mag_assets/` and the app shell, in a commit by `magmonium[bot]` that credits
+  you.
+
+### When linking is refused
+
+| Message | What it means | Fix |
+| --- | --- | --- |
+| That is not a GitHub repository URL | The text is not one of the forms above. | Paste the URL from the repository's GitHub page. |
+| The Magmonium GitHub App is not installed on that repository | Step 2 is missing, was installed on a different repository, or is still waiting for an organization owner's approval. | [Install it](https://github.com/apps/magmonium/installations/new) on this exact repository (or add the repository under **Configure**), then link again. |
+| That repository is already linked to another App | Each repository serves one App, even after it is renamed or moved on GitHub. | Create a new repository for this App. |
+| That repository holds an app without a design. Use an empty one. | The default branch has files other than `README.md`, `LICENSE`, `.gitignore`, and no `.magmonium/` folder. | Use an empty repository. |
+| GitHub refused — the app may have been uninstalled or the repository deleted | GitHub would not answer for that repository. | Check that the repository exists and the GitHub App is still installed on it. |
+| This server has no GitHub App configured | This Magmonium server is not set up for GitHub. | Contact the platform admin. |
+| Only the App's Owner can link its repository. | You are a Collaborator. | Ask the Owner to link it. |
+
+### Moving to another repository
+
+The Owner can link the App to a different repository at any time, under the
+same three steps and the same rules. Nothing is copied: the old repository
+keeps what it has, and the next Push writes the whole app into the new one
+from scratch. Deploys are not affected. They use your deploy token, not the
+repository.
+
+Remember to set the release secrets again in the new repository (see the
+release guide).
+
+### Reinstalled the GitHub App?
+
+If you uninstalled and reinstalled the Magmonium GitHub App, Pull and Push
+fail with *GitHub refused*. The Owner fixes this by linking the **same**
+repository again. Linking an App to its own repository is always allowed.
+
+## Who can write
+
+| Role | Link a repository | Pull | Push | Create a branch |
+| --- | --- | --- | --- | --- |
+| Owner | yes | yes | yes | yes |
+| Collaborator | no | yes | yes | yes |
+| Anyone else | no | no | no | no |
+
+Collaborators do **not** need to be added on GitHub. Every write goes through
+the Magmonium GitHub App and is allowed by the Store role alone, so removing
+someone from the App also ends their access to the repository.
+
+Commits are made by `magmonium[bot]` and credit the person who pushed with a
+`Co-authored-by:` line.
+
+## Working from the editor
+
+Open the editor and pick the App. You can also compose without one, using
+**Continue unlinked**: Save, Download and Run all still work. Push appears once
+you create an App for the workspace. Its link is prefilled from the app's name.
+
+### The everyday loop
+
+| Gesture | Where it writes | When |
+| --- | --- | --- |
+| **Save** | your linked local folder | as often as you like |
+| **Run** / **Sync** | the Run window | to see the app running |
+| **Push** | a branch of the AppRepo | when a piece of work is done |
+
+Push is the last step after local work, not something to press every few
+minutes.
+
+### Pull
+
+**Pull** replaces the workspace with the design from one branch (`dev` unless
+you pick another). The editor rebuilds the code from the design. It never
+reads the emitted code back.
+
+If the workspace has edits you have not Pushed, Pull asks first and tells you
+what it will drop. There is only one workspace.
+
+A branch that does not exist yet is read from the repository's default branch.
+
+### Push
+
+**Push** makes one commit holding the emitted app and the design.
+
+- **Branch.** Pushes go to `dev` by default. `dev` is created from the default
+  branch on the first Push.
+- **Never `main`.** `main` takes changes by pull request on GitHub.
+- **Commit message.** The editor drafts it in the form
+  `type(feature): few words`, from what changed in the design since your last
+  Pull or Push. Your AI provider writes the draft if you have set one up. You
+  always see the message and can edit it before it goes.
+- **What it deletes.** A Push removes files only inside the folders the editor
+  owns: `mag_assets/`, `src/app/features/`, `src/app/pages/`,
+  `src/app/widgets/` and `.magmonium/`. Hand-written code in
+  `src/app/custom/`, the shell, and anything else you added are never deleted.
+- **Blocked.** Push refuses while the design has violations or a function body
+  that does not compile. The editor lists the reasons.
+
+### When the branch has moved
+
+Push only goes through if the branch is still where you last Pulled or Pushed
+it. If someone else pushed in the meantime, you see
+*The branch has moved since you pulled*. Push is never forced. You have two
+options:
+
+- **Pull again.** You get their changes, but you lose your unpushed edits.
+- **Push to a new branch.** Your work lands on its own branch, for example
+  `feature/my-change`. Merge it on GitHub with a pull request.
+
+To avoid this when several people work on one App, give each person their own
+branch: use **+ New branch** in the branch picker.
+
+## Branches
+
+| Branch | Role |
+| --- | --- |
+| `main` | Releases. Changes arrive only by pull request on GitHub. CD runs here. |
+| `dev` | The default Push target. Open pull requests from here into `main`. |
+| `feature/...` | Optional. One per person or per piece of work. |
+
+**Create Branch** makes a branch at the commit your workspace stands on, or at
+the head of the default branch. Branch names may use letters, digits, `.`, `_`,
+`-` and `/`. A branch can only be created once the repository has at least one
+commit. Push first to start it.
+
+## From repository to Store
+
+Linking and pushing never deploy anything. The path to users is:
+
+1. **Push** to `dev` from the editor.
+2. Open a **pull request** `dev → main` on GitHub. CI checks it.
+3. Bump `version:` in `mag_assets/remote/<app>.yml` and **merge**. CD builds
+   the bundle and deploys it to the App's beta tier.
+4. **Preview** beta from the Store. The Owner then **Publishes** it to users.
+
+The release guide covers the repository secrets, the deploy token, and the
+version gate that decides when CD deploys.
+
+## Troubleshooting
+
+| Message | What happened | Fix |
+| --- | --- | --- |
+| This App has no linked repository | The App has no AppRepo yet. | The Owner links one. |
+| The repository has no commits yet. Push first to start it | You tried to create a branch in an empty repository. | Push once, then create the branch. |
+| main takes changes by pull request on GitHub | You tried to Push to, or create, `main`. | Push to `dev` or a feature branch. |
+| This branch exists, pick it from the list | The new branch name is taken. | Pick that branch, or choose another name. |
+| Nothing to Push. The workspace matches its last Pull or Push. | There are no design changes. | None needed. |
+| The design in this branch could not be read | The `.magmonium/` folder on that branch is damaged or was edited by hand. | Restore it from history on GitHub, or Pull another branch. |
+| GitHub refused — the app may have been uninstalled or the repository deleted | GitHub refused the request. | [Reinstall the GitHub App](https://github.com/apps/magmonium/installations/new), then have the Owner link the same repository again. |

package/assets/i18n/en.json

@@ -593,6 +593,7 @@
   "pinned": "Pinned",
   "pitcairn-islands": "Pitcairn Islands",
   "please-select": "Please select",
+  "plugin-screen-not-found": "This app offers no plugin by that name",
   "poland": "Poland",
   "portfolio": "Portfolio",
   "portfolio-analysis": "Portfolio Analysis",