@quatronic/qore 0.1.1 → 0.1.2

package/README.md

@@ -176,6 +176,85 @@ If a repository resolves to no module on any portal you're logged in to,
 the error lists the portals it tried and, when a staging repository looks
 likely, suggests `qore login --portal staging`.
 
+### Workspaces
+
+`qore clone` sets up a local directory holding one or more of an app's
+modules, each in its own repository; `qore sync` keeps that directory in
+step with the app afterwards.
+
+```sh
+qore clone <app>              # clones every module of <app> into ./<app-slug>
+qore clone <app> <dir>        # ...into <dir> instead
+cd <app-slug>
+qore status                   # app-level table, one row per module/environment
+cd <module>
+qore env pull                 # no trust prompt — a clone made by qore is already trusted
+cd ..
+qore sync                     # clone any module that's new, fetch the rest
+qore sync --pull              # ...and fast-forward every clean repository with an upstream
+```
+
+- **`--protocol https|ssh`** picks the clone URL (default `https`). `ssh`
+  rewrites `https://github.com/o/r` to `git@github.com:o/r.git`; your own
+  git `insteadOf` config still applies on top of either.
+- **`--tenant <slug>`** on `qore clone` disambiguates an app slug that
+  exists in more than one tenant you have access to.
+- **The workspace file** is `qore.workspace.json` at the directory `qore
+  clone` created, holding `{"schemaVersion": 1, "portal": "<apiOrigin>",
+  "appId": "<uuid>"}`. It never lists modules — those always come from the
+  portal, so a module added to the app later shows up on the next `qore
+  sync` with no local change needed. `qore` finds it by walking up from the
+  current directory (stopping at your home directory). The module commands
+  (`env pull`, `run`, …), `qore status` and `qore sync` pick up its portal
+  (and, for a module shared by several apps, its app) automatically when run
+  from inside the workspace — including from a module's own repository;
+  `qore clone`, `qore whoami` and `qore tenant` do not read it. An explicit
+  `--portal` flag always wins over it. `qore status` shows the app-level
+  table only when run in the directory that holds `qore.workspace.json`
+  itself (not inside one of its module repositories, which shows that
+  module).
+- **Nothing is ever deleted, moved or overwritten.** A present module
+  directory is left exactly as it is; `sync` only fetches into it, and
+  only fast-forwards with `--pull`, and only when the tree is clean and has
+  an upstream — a dirty tree, one with no upstream, or one that would need
+  a merge is reported, never touched. `sync` runs a plain `git fetch` (no
+  `--prune`). A module's directory whose `origin` doesn't point at that
+  module's repository is reported as re-pointed, and one that isn't a git
+  repository at all is reported too — neither is repaired; move it aside
+  and run `qore sync` again. A repository directory in the workspace that
+  isn't one of the app's modules (typically a module that left the app) is
+  reported as removed, and left on disk.
+- **A target directory that already holds something else** — someone
+  else's files, or another app's or portal's workspace — makes `qore
+  clone` fail with `QORE_WORKSPACE_CONFLICT` before writing anything,
+  including `qore.workspace.json`. Pick a different directory
+  (`qore clone <app> <dir>`).
+- **Per-module clone failures** are diagnosed individually and don't stop
+  the rest of the run:
+  - `QORE_GITHUB_NOT_LINKED` — your GitHub account isn't linked in Qore;
+    link it at the account page, then `qore sync`.
+  - `QORE_REPO_NO_ACCESS` — you have no seat on the repository; the error
+    names the dev team(s) that build the module and their maintainers to ask.
+  - `QORE_REPO_ACCESS_PENDING` — access was granted recently, or your
+    GitHub organisation invitation isn't accepted yet; the error links the
+    invitation page.
+  - `QORE_GIT_AUTH` — git itself couldn't authenticate (no SSH key,
+    GitHub's SSH host key not accepted yet, no `gh auth login`, or SSO
+    authorisation needed for the org); the error names the fix.
+
+  `clone`/`sync` exits `0` when at least one module cloned or was already
+  present and every failure is one of the first three above
+  (`QORE_GITHUB_NOT_LINKED`, `QORE_REPO_NO_ACCESS`,
+  `QORE_REPO_ACCESS_PENDING`) — so a developer missing a seat on one module
+  of a multi-module app still gets a usable workspace for the rest.
+  `QORE_GIT_AUTH` is not an access failure in this sense: it fails the run
+  (exit `5`). Any other failure, or a run where nothing succeeded at all,
+  exits with that failure's own code. With `--json`, once the per-module
+  loop has run its results are under `data.results` (or
+  `error.details.results` on failure); an error before that (not logged in,
+  no workspace, a conflicting target directory) is an ordinary error
+  document without results.
+
 ### `--json`
 
 Every command accepts `--json`, which prints exactly one JSON document on