@magmonium/one 0.4.26 → 0.4.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/assets/docs/en/app-repo.md +93 -176
  2. package/package.json +1 -1
package/assets/docs/en/app-repo.md CHANGED
@@ -1,96 +1,66 @@
1
1
  # Linking an mm App to GitHub
2
2
 
3
- How an App's source gets into a GitHub repository, and how you and your
4
- collaborators keep working on it from the editor. Releasing what is in that
5
- repository is a separate step, covered in the release guide.
3
+ App source into GitHub repo, keep working from editor. Release = separate step, see release guide.
6
4
 
7
5
  ## What the repository holds
8
6
 
9
- Each App has one repository: its **AppRepo**. It holds two things:
7
+ One App = one repo: its **AppRepo**.
10
8
 
11
9
  | Path | What it is |
12
10
  | --- | --- |
13
- | `.magmonium/` | The design: Screens, Features, state, rules, nav and assets as you composed them. This is what the editor reads back. |
14
- | `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. |
11
+ | `.magmonium/` | Design: Screens, Features, state, rules, nav, assets. Editor reads this back. |
12
+ | `src/app/custom/`, `mag_assets/` and the shell | Hand-written, editor can't regenerate: own components, assets, `package.json`, `angular.json`, CI workflows. |
15
13
 
16
- 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.
14
+ Generated code — `src/app/features/`, `pages/`, `widgets/`, `shared/lib/`, `shared/type/`, router + provide overlays — **not** committed. `npm start`, `npm run build*`, `npm test` regenerate it from `.magmonium/` via `@magmonium/cli` (`npm run gen:code`). Clone builds after `npm install`, no editor needed. `.gitignore` excludes it.
17
15
 
18
- The Store records which repository belongs to which App. The repository's own
19
- files only carry the App's id, so moving the App to another repository leaves
20
- nothing stale behind.
16
+ Store records repo ↔ App. Repo files carry only App id, so moving App leaves nothing stale.
21
17
 
22
- One repository serves one App. A repository already linked to another App is
23
- refused.
18
+ One repo per App. Repo linked to another App refused.
24
19
 
25
20
  ## Linking, step by step
26
21
 
27
- Linking takes three steps. Steps 1 and 2 happen on GitHub, step 3 in
28
- Magmonium. Do them in this order: Magmonium checks the repository at the
29
- moment you link, so the GitHub side has to be ready first.
22
+ Three steps, in order. Magmonium checks repo at link time, so GitHub side first.
30
23
 
31
24
  | Step | Where | Who |
32
25
  | --- | --- | --- |
33
- | 1. Create the repository | GitHub | anyone who can create repositories there |
34
- | 2. Install the Magmonium GitHub App on it | GitHub | an admin of that repository |
35
- | 3. Link it to the App | Store or editor | the App's Owner |
26
+ | 1. Create the repository | GitHub | anyone who can create repos there |
27
+ | 2. Install the Magmonium GitHub App on it | GitHub | repo admin |
28
+ | 3. Link it to the App | Store or editor | App's Owner |
36
29
 
37
- The person doing step 2 and the App's Owner are usually the same person, but
38
- they do not have to be. Magmonium never asks for your GitHub password or a
39
- GitHub token. The installation in step 2 is the only permission it uses.
30
+ Step 2 person and Owner can differ. Magmonium never asks GitHub password or token. Step 2 install = only permission used.
40
31
 
41
32
  ### Step 1 — Create the repository
42
33
 
43
- On GitHub, choose **New repository** under your account or an organization.
34
+ GitHub → **New repository**, under account or org.
44
35
 
45
- - **Name it after the App.** Using the App link (for example `m-orders`)
46
- keeps things easy to find, but any name works.
47
- - **Private or public.** Either works.
48
- - **Contents.** Leave it empty. Adding a `README.md`, `LICENSE` or
49
- `.gitignore` is fine. Do not add a `package.json` or any app code: the first
50
- Push writes the whole app for you.
36
+ - **Name.** App link (e.g. `m-orders`) easiest. Any name works.
37
+ - **Private or public.** Either.
38
+ - **Contents.** Empty. `README.md`, `LICENSE`, `.gitignore` OK. No `package.json` or app code: first Push writes whole app.
51
39
 
52
- You can also reuse a repository that already holds a Magmonium design, that
53
- is, one with a `.magmonium/` folder on its default branch. Do this, for
54
- example, when you move an App to a new repository or restore one.
40
+ Reuse OK: repo with `.magmonium/` on default branch (move or restore App).
55
41
 
56
- A repository that holds anything else, such as a hand-written Angular app, is
57
- refused. It has no design for the editor to read, and the first Push would
58
- overwrite its files.
42
+ Anything else (e.g. hand-written Angular app) refused. No design to read, first Push would overwrite.
59
43
 
60
44
  ### Step 2 — Install the Magmonium GitHub App
61
45
 
62
- This step is what proves to Magmonium that the repository is yours to hand
63
- over. GitHub only lets an admin of the repository install an app on it.
64
-
65
- 1. Open the install page:
66
- **[github.com/apps/magmonium/installations/new](https://github.com/apps/magmonium/installations/new)**.
67
- The same link appears as **Install the Magmonium GitHub App** next to the
68
- repository field when you link, and again if a link is refused.
69
- 2. On GitHub, pick the **account or organization** that owns the repository.
70
- 3. Choose **Only select repositories** and select the repository from step 1.
71
- *All repositories* also works, but gives Magmonium access to more than it
72
- needs.
46
+ Proves repo yours to hand over. Only repo admin can install.
47
+
48
+ 1. Press **Install the Magmonium GitHub App** next to repository field (also shown when link refused).
49
+ 2. Pick **account or organization** owning repo.
50
+ 3. Choose **Only select repositories**, select step 1 repo. *All repositories* works but grants more than needed.
73
51
  4. Press **Install**.
74
52
 
75
- **If the GitHub App is already installed on that account**, GitHub shows
76
- **Configure** instead of **Install**. Open it and add the new repository
77
- under *Repository access*. Then press **Save**.
53
+ **Already installed on that account?** GitHub shows **Configure**. Add repo under *Repository access*, press **Save**.
78
54
 
79
- **For an organization repository**, an organization owner may need to install
80
- the app or approve your request. If GitHub says *request sent*, the link only
81
- works after an owner approves it.
55
+ **Org repo?** Org owner may need to install or approve. *Request sent* = link works only after approval.
82
56
 
83
- Magmonium uses the installation only to read and write the files of the
84
- repositories you selected, which is what Pull and Push need. Remove a
85
- repository from the installation, or uninstall the app, and Magmonium can no
86
- longer reach it.
57
+ Install used only to read/write files of selected repos (Pull + Push). Remove repo or uninstall → Magmonium loses access.
87
58
 
88
59
  ### Step 3 — Link it to the App
89
60
 
90
- Only the App's **Owner** can link. Collaborators see *Only the App's Owner can
91
- link its repository.*
61
+ Only **Owner** links. Collaborators see *Only the App's Owner can link its repository.*
92
62
 
93
- Enter the repository in any of these forms:
63
+ Accepted forms:
94
64
 
95
65
  ```text
96
66
  https://github.com/acme/orders
@@ -99,88 +69,62 @@ git@github.com:acme/orders
99
69
  acme/orders
100
70
  ```
101
71
 
102
- You can link from three places.
72
+ Three places to link.
103
73
 
104
74
  #### When you create an App in the Store
105
75
 
106
- 1. In the Store, start **Create App**.
107
- 2. In the **Info** step, fill in **App Link**, **App Type** and
108
- **Repository URL**. All three are required.
109
- 3. Continue. Magmonium creates the App and links the repository in one go.
110
- - **Link accepted:** the wizard moves on to **Deploy Setup** and then
111
- **How to Publish**.
112
- - **Link refused:** the App is **not** created. The wizard stays on
113
- **Info**, shows the reason, and offers **Install the Magmonium GitHub
114
- App**. Fix the problem, then continue again.
76
+ 1. Store → **Create App**.
77
+ 2. **Info** step: fill **App Link**, **App Type**, **Repository URL**. All required.
78
+ 3. Continue. App created + repo linked together.
79
+ - **Link accepted:** → **Deploy Setup** → **How to Publish**.
80
+ - **Link refused:** App **not** created. Stays on **Info**, shows reason, offers **Install the Magmonium GitHub App**. Fix, continue again.
115
81
 
116
- While the App is still a draft, you can go back to **Info** and change the
117
- **Repository URL**. A changed URL is checked again, exactly like the first
118
- link.
82
+ Draft App: go back to **Info**, change **Repository URL**. Rechecked like first link.
119
83
 
120
84
  #### From the editor, for an App you already have
121
85
 
122
- 1. In the editor's page menu, choose **Open App**.
123
- 2. Pick the App. If it has no repository yet, the editor shows **Link
124
- repository** with the install link and a **GitHub repository** field.
125
- 3. Enter the repository and press **Link repository**.
126
- 4. **Link accepted:** the editor moves on to choosing a **Branch** to Pull
127
- (`dev` by default). Pulling a fresh repository gives you an **empty**
128
- workspace named after the App, ready to compose in. It replaces whatever
129
- the workspace held before, so if you already composed something you want
130
- to keep, use the next path instead.
86
+ 1. Page menu → **Open App**.
87
+ 2. Pick App. No repo yet → **Link repository** with install button + **GitHub repository** field.
88
+ 3. Enter repo, press **Link repository**.
89
+ 4. **Link accepted:** pick **Branch** to Pull (`dev` default). Fresh repo → **empty** workspace named after App. Replaces current workspace — have work to keep? Use next path.
131
90
 
132
91
  #### From the editor, for a workspace with no App yet
133
92
 
134
- If you composed first and have no App yet:
93
+ Composed first, no App:
135
94
 
136
- 1. Choose **Open App**, then **Create App**. The editor offers this when the
137
- workspace has Screens but no App.
138
- 2. Fill in the name, **App link**, type, description and **GitHub
139
- repository**. The link is prefilled from the app's name.
95
+ 1. **Open App** → **Create App**. Offered when workspace has Screens, no App.
96
+ 2. Fill name, **App link**, type, description, **GitHub repository**. Link prefilled from name.
140
97
  3. Press **Create App**.
141
- - **Link accepted:** the editor keeps your workspace, links it to the new
142
- App, and goes straight to **Push**.
143
- - **Link refused:** unlike the Store wizard, the App **is** created. The
144
- editor shows the reason on the **Link repository** step, so you can fix
145
- it and link again without creating a second App.
98
+ - **Link accepted:** workspace kept, linked to new App, straight to **Push**.
99
+ - **Link refused:** unlike Store, App **is** created. Reason shown on **Link repository** step. Fix, link again, no second App.
146
100
 
147
101
  ### Check that it worked
148
102
 
149
- - In the Store, the App's deployment page shows the repository URL.
150
- - In the editor, **Open App** for that App now goes straight to choosing a
151
- **Branch** instead of asking for a repository.
152
- - After your first Push, the repository on GitHub has a `dev` branch holding
153
- `.magmonium/`, `mag_assets/` and the app shell, in a commit by `magmonium[bot]` that credits
154
- you.
103
+ - Store: App deployment page shows repo URL.
104
+ - Editor: **Open App** goes straight to **Branch**, no repo prompt.
105
+ - After first Push: GitHub repo has `dev` branch with `.magmonium/`, `mag_assets/`, app shell, commit by `magmonium[bot]` crediting you.
155
106
 
156
107
  ### When linking is refused
157
108
 
158
109
  | Message | What it means | Fix |
159
110
  | --- | --- | --- |
160
- | 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. |
161
- | 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. |
162
- | 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. |
163
- | 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. |
164
- | 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. |
165
- | This server has no GitHub App configured | This Magmonium server is not set up for GitHub. | Contact the platform admin. |
166
- | Only the App's Owner can link its repository. | You are a Collaborator. | Ask the Owner to link it. |
111
+ | That is not a GitHub repository URL | Not one of forms above. | Paste URL from repo's GitHub page. |
112
+ | The Magmonium GitHub App is not installed on that repository | Step 2 missing, on wrong repo, or awaiting org owner approval. | Install on this exact repo (or add under **Configure**), link again. |
113
+ | That repository is already linked to another App | One repo per App, even after rename/move on GitHub. | New repo for this App. |
114
+ | That repository holds an app without a design. Use an empty one. | Default branch has files beyond `README.md`, `LICENSE`, `.gitignore`, no `.magmonium/`. | Use empty repo. |
115
+ | GitHub refused — the app may have been uninstalled or the repository deleted | GitHub won't answer for repo. | Check repo exists + GitHub App still installed. |
116
+ | This server has no GitHub App configured | Server not set up for GitHub. | Contact platform admin. |
117
+ | Only the App's Owner can link its repository. | You are Collaborator. | Ask Owner. |
167
118
 
168
119
  ### Moving to another repository
169
120
 
170
- The Owner can link the App to a different repository at any time, under the
171
- same three steps and the same rules. Nothing is copied: the old repository
172
- keeps what it has, and the next Push writes the whole app into the new one
173
- from scratch. Deploys are not affected. They use your deploy token, not the
174
- repository.
121
+ Owner can relink anytime, same steps + rules. Nothing copied: old repo keeps its content, next Push writes whole app fresh into new one. Deploys unaffected (use deploy token, not repo).
175
122
 
176
- Remember to set the release secrets again in the new repository (see the
177
- release guide).
123
+ Set release secrets again in new repo (see release guide).
178
124
 
179
125
  ### Reinstalled the GitHub App?
180
126
 
181
- If you uninstalled and reinstalled the Magmonium GitHub App, Pull and Push
182
- fail with *GitHub refused*. The Owner fixes this by linking the **same**
183
- repository again. Linking an App to its own repository is always allowed.
127
+ Uninstall + reinstall → Pull/Push fail with *GitHub refused*. Owner relinks **same** repo. Relinking own repo always allowed.
184
128
 
185
129
  ## Who can write
186
130
 
@@ -190,107 +134,80 @@ repository again. Linking an App to its own repository is always allowed.
190
134
  | Collaborator | no | yes | yes | yes |
191
135
  | Anyone else | no | no | no | no |
192
136
 
193
- Collaborators do **not** need to be added on GitHub. Every write goes through
194
- the Magmonium GitHub App and is allowed by the Store role alone, so removing
195
- someone from the App also ends their access to the repository.
137
+ Collaborators **not** added on GitHub. All writes go via Magmonium GitHub App, allowed by Store role alone. Remove from App = repo access ends.
196
138
 
197
- Commits are made by `magmonium[bot]` and credit the person who pushed with a
198
- `Co-authored-by:` line.
139
+ Commits by `magmonium[bot]`, credit pusher via `Co-authored-by:` line.
199
140
 
200
141
  ## Working from the editor
201
142
 
202
- Open the editor and pick the App. You can also compose without one, using
203
- **Continue unlinked**: Save, Download and Run all still work. Push appears once
204
- you create an App for the workspace. Its link is prefilled from the app's name.
143
+ Open editor, pick App. Or **Continue unlinked**: Save, Download, Run still work. Push appears after creating App for workspace (link prefilled from name).
205
144
 
206
145
  ### The everyday loop
207
146
 
208
147
  | Gesture | Where it writes | When |
209
148
  | --- | --- | --- |
210
- | **Save** | your linked local folder | as often as you like |
211
- | **Run** / **Sync** | the Run window | to see the app running |
212
- | **Push** | a branch of the AppRepo | when a piece of work is done |
149
+ | **Save** | linked local folder | anytime |
150
+ | **Run** / **Sync** | Run window | see app running |
151
+ | **Push** | AppRepo branch | work piece done |
213
152
 
214
- Push is the last step after local work, not something to press every few
215
- minutes.
153
+ Push = last step after local work, not every few minutes.
216
154
 
217
155
  ### Pull
218
156
 
219
- **Pull** replaces the workspace with the design from one branch (`dev` unless
220
- you pick another). The editor rebuilds the code from the design. It never
221
- reads the emitted code back.
157
+ **Pull** replaces workspace with design from one branch (`dev` unless picked). Editor rebuilds code from design, never reads emitted code back.
222
158
 
223
- If the workspace has edits you have not Pushed, Pull asks first and tells you
224
- what it will drop. There is only one workspace.
159
+ Unpushed edits → Pull asks first, lists what drops. One workspace only.
225
160
 
226
- A branch that does not exist yet is read from the repository's default branch.
161
+ Missing branch → read from default branch.
227
162
 
228
163
  ### Push
229
164
 
230
- **Push** makes one commit holding the emitted app and the design.
165
+ **Push** = one commit, emitted app + design.
231
166
 
232
- - **Branch.** Pushes go to `dev` by default. `dev` is created from the default
233
- branch on the first Push.
167
+ - **Branch.** `dev` default. Created from default branch on first Push.
234
168
  - **Never `main`.** `main` takes changes by pull request on GitHub.
235
- - **Commit message.** The editor drafts it in the form
236
- `type(feature): few words`, from what changed in the design since your last
237
- Pull or Push. Your AI provider writes the draft if you have set one up. You
238
- always see the message and can edit it before it goes.
239
- - **What it deletes.** A Push removes files only inside the folders the editor
240
- owns: `mag_assets/`, `src/app/features/`, `src/app/pages/`,
241
- `src/app/widgets/` and `.magmonium/`. Hand-written code in
242
- `src/app/custom/`, the shell, and anything else you added are never deleted.
243
- - **Blocked.** Push refuses while the design has violations or a function body
244
- that does not compile. The editor lists the reasons.
169
+ - **Commit message.** Drafted as `type(feature): few words` from design changes since last Pull/Push. AI provider drafts if set up. Always visible + editable before send.
170
+ - **What it deletes.** Only inside editor-owned folders: `mag_assets/`, `src/app/features/`, `src/app/pages/`, `src/app/widgets/`, `.magmonium/`. `src/app/custom/`, shell, other added files never deleted.
171
+ - **Blocked.** Refused while design has violations or function body won't compile. Editor lists reasons.
245
172
 
246
173
  ### When the branch has moved
247
174
 
248
- Push only goes through if the branch is still where you last Pulled or Pushed
249
- it. If someone else pushed in the meantime, you see
250
- *The branch has moved since you pulled*. Push is never forced. You have two
251
- options:
175
+ Push only if branch still where you last Pulled/Pushed. Someone pushed meanwhile → *The branch has moved since you pulled*. Never forced. Two options:
252
176
 
253
- - **Pull again.** You get their changes, but you lose your unpushed edits.
254
- - **Push to a new branch.** Your work lands on its own branch, for example
255
- `feature/my-change`. Merge it on GitHub with a pull request.
177
+ - **Pull again.** Get their changes, lose unpushed edits.
178
+ - **Push to a new branch.** e.g. `feature/my-change`. Merge on GitHub via pull request.
256
179
 
257
- To avoid this when several people work on one App, give each person their own
258
- branch: use **+ New branch** in the branch picker.
180
+ Many people on one App → one branch each: **+ New branch** in branch picker.
259
181
 
260
182
  ## Branches
261
183
 
262
184
  | Branch | Role |
263
185
  | --- | --- |
264
- | `main` | Releases. Changes arrive only by pull request on GitHub. CD runs here. |
265
- | `dev` | The default Push target. Open pull requests from here into `main`. |
266
- | `feature/...` | Optional. One per person or per piece of work. |
186
+ | `main` | Releases. Pull request only. CD runs here. |
187
+ | `dev` | Default Push target. PR from here into `main`. |
188
+ | `feature/...` | Optional. Per person or per work piece. |
267
189
 
268
- **Create Branch** makes a branch at the commit your workspace stands on, or at
269
- the head of the default branch. Branch names may use letters, digits, `.`, `_`,
270
- `-` and `/`. A branch can only be created once the repository has at least one
271
- commit. Push first to start it.
190
+ **Create Branch** at workspace commit or default branch head. Names: letters, digits, `.`, `_`, `-`, `/`. Needs at least one commit — Push first.
272
191
 
273
192
  ## From repository to Store
274
193
 
275
- Linking and pushing never deploy anything. The path to users is:
194
+ Link + Push never deploy. Path to users:
276
195
 
277
- 1. **Push** to `dev` from the editor.
278
- 2. Open a **pull request** `dev → main` on GitHub. CI checks it.
279
- 3. Bump `version:` in `mag_assets/remote/<app>.yml` and **merge**. CD builds
280
- the bundle and deploys it to the App's beta tier.
281
- 4. **Preview** beta from the Store. The Owner then **Publishes** it to users.
196
+ 1. **Push** to `dev` from editor.
197
+ 2. **Pull request** `dev → main` on GitHub. CI checks.
198
+ 3. Bump `version:` in `mag_assets/remote/<app>.yml`, **merge**. CD builds bundle, deploys to beta tier.
199
+ 4. **Preview** beta in Store. Owner **Publishes** to users.
282
200
 
283
- The release guide covers the repository secrets, the deploy token, and the
284
- version gate that decides when CD deploys.
201
+ Release guide covers repo secrets, deploy token, version gate.
285
202
 
286
203
  ## Troubleshooting
287
204
 
288
205
  | Message | What happened | Fix |
289
206
  | --- | --- | --- |
290
- | This App has no linked repository | The App has no AppRepo yet. | The Owner links one. |
291
- | 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. |
292
- | main takes changes by pull request on GitHub | You tried to Push to, or create, `main`. | Push to `dev` or a feature branch. |
293
- | This branch exists, pick it from the list | The new branch name is taken. | Pick that branch, or choose another name. |
294
- | Nothing to Push. The workspace matches its last Pull or Push. | There are no design changes. | None needed. |
295
- | 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. |
296
- | 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. |
207
+ | This App has no linked repository | No AppRepo yet. | Owner links one. |
208
+ | The repository has no commits yet. Push first to start it | Branch create in empty repo. | Push once, then create branch. |
209
+ | main takes changes by pull request on GitHub | Push to / create `main`. | Push to `dev` or feature branch. |
210
+ | This branch exists, pick it from the list | Name taken. | Pick it, or other name. |
211
+ | Nothing to Push. The workspace matches its last Pull or Push. | No design changes. | None. |
212
+ | The design in this branch could not be read | `.magmonium/` on branch damaged or hand-edited. | Restore from GitHub history, or Pull other branch. |
213
+ | GitHub refused — the app may have been uninstalled or the repository deleted | GitHub refused request. | Reinstall GitHub App, Owner relinks same repo. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@magmonium/one",
3
- "version": "0.4.26",
3
+ "version": "0.4.27",
4
4
  "description": "Magmonium One — Angular design-system primitives for mm Apps",
5
5
  "author": "magmonium",
6
6
  "license": "MIT",