@quatronic/qore 0.1.0 → 0.1.2

package/README.md

@@ -20,6 +20,9 @@ qore tenant list        # list tenants you have access to
 qore tenant use <slug>  # set the active tenant
 qore logout
 qore version            # CLI + portal version info
+
+qore env pull           # write this module's local secrets into an env file
+qore run -- <command>   # run a command with those secrets in its environment
 ```
 
 ### Portals
@@ -33,6 +36,225 @@ it reports).
 qore login --portal staging
 ```
 
+### Repository context
+
+Commands like `qore status` need to know which module you mean. By default
+that comes from the git remote of the repository you're standing in:
+`qore` reads `git remote -v`, prefers `origin`, falls back to `upstream`,
+then the rest in git order, and resolves the remote's URL to a module on
+the portal. Working from a personal fork whose `origin` the portal doesn't
+know? As long as an `upstream` remote points at the real repository, that one
+resolves — the context line then says `(upstream)`.
+
+Pass `--module <slug|id>` to pick a module explicitly; the flag always wins
+over the git remote. Inside a repository, `qore` still looks up the remote's
+own module (from the cache, or with one extra request) only so the context
+line can tell you when the flag overrides it. If a module is linked to more
+than one app you can read, add `--app <slug|id>` to disambiguate.
+
+Every context-aware command prints a context line to stderr (never stdout,
+so it's safe to pipe `--json` output):
+
+```
+→ <Tenant> / <App> / <module>  (<source>)
+```
+
+`<source>` is the remote name that resolved it (`origin`, `upstream`, …),
+or `--module` when you passed the flag. If `--module` resolves to a
+different module than the repository's own remote would have, it reads
+`--module, overrides <remote>`. With `--json`, this same information is
+under `data.context` instead, and nothing about it goes to stderr.
+
+#### `qore status`
+
+Shows deployment and health per environment for the current module:
+
+```sh
+qore status
+```
+
+| Column | Meaning |
+|--------|---------|
+| ENV | Environment name |
+| DEPLOY | Deployment status, or `paused` |
+| COMMIT | Deployed commit SHA |
+| DEPLOYED | How long ago that commit was deployed |
+| APP HEALTH | The app's public health check (not the module's) |
+
+#### `qore env pull`
+
+Writes this module's local secrets into an env file in the current
+repository:
+
+```sh
+qore env pull
+```
+
+- The target file defaults to the module type's own convention (e.g.
+  `.env.local`), or `.qore.json`'s `envFile`, or `--target <path>` — always
+  resolved against, and required to stay inside, the repository.
+- If the file doesn't exist yet, it's seeded from `.env.example` when one is
+  present.
+- Existing values you've hand-edited are kept by default. A key the portal
+  manages (e.g. `CONN_*`, `DATABASE_URL`) is always taken from the portal.
+  For any other key that differs between your file and the portal, pass
+  `--use-portal` to take the portal's value, or answer the interactive
+  prompt per key (which shows only the **length** of each value, never its
+  content — see "Values are never printed" below).
+- The file is written with mode `0600` via a temp file in the same
+  directory, then renamed over the target — it's never truncated in place.
+  (On Windows, POSIX file modes don't apply — setting `0600` there is a
+  no-op; there's no equivalent file-permission hardening on that platform.)
+
+**First use of a repository** requires confirmation — see "Trust on first
+use" below. **Values are never printed**: not in `qore env pull`'s output,
+not in the interactive conflict prompt, not in `--verbose` logs, and not in
+the portal's own audit trail, which records key names only (see
+`app.local_env.fetched`).
+
+#### `qore run`
+
+Runs a command with this module's local secrets injected into its
+environment, without ever writing them to disk:
+
+```sh
+qore run -- node server.js
+qore run -- pnpm dev
+```
+
+- Secrets are fetched fresh on every `run` — never cached — merged with
+  your current environment, and passed only to the child process.
+- The command runs without a shell (`shell: false`); everything after `--`
+  is passed to it verbatim, including its own flags (a `--json` or
+  `--no-input` after `--` is the child's, never `qore`'s own). On Windows,
+  this is true in spirit but not literally for `.cmd` shims (e.g. `pnpm`,
+  `npm`, or anything installed as a `.cmd` wrapper): `cross-spawn` runs
+  those through `cmd.exe /d /s /c` under the hood, with its own escaping.
+  Pressing Ctrl+C there can also surface cmd's own
+  `Terminate batch job (Y/N)?` prompt.
+- The child's exit code, or the signal it was killed with (e.g. Ctrl+C →
+  128+signal), becomes `qore run`'s own exit code.
+- **Secrets live in the child's environment**, which is inherited by any
+  process the child spawns (its grandchildren) and is readable by other
+  processes running as the same user (`/proc/<pid>/environ`, `ps eww`) —
+  no worse than a `.env.local` on disk, but worth knowing before running an
+  untrusted command this way.
+
+#### `.qore.json`
+
+An optional file at the repository root that configures `qore env pull`
+for that repository. Schema:
+[`schema/qore.schema.json`](./schema/qore.schema.json).
+
+```json
+{
+  "$schema": "https://unpkg.com/@quatronic/qore/schema/qore.schema.json",
+  "envFile": ".env.local",
+  "localSecrets": ["MY_LOCAL_OVERRIDE"]
+}
+```
+
+It never holds a portal URL, tenant, app or module id — those are always
+resolved from the git remote or `--module`/`--app`, never committed.
+
+#### Trust on first use
+
+The first time you run `qore env pull` or `qore run` against a given
+repository (for a given module), `qore` asks you to confirm before pulling
+secrets into it — trust-on-first-use, recorded locally, not a portal-side
+grant. Pass `--yes` to trust non-interactively (CI, scripts) instead of
+being prompted.
+
+#### Resolution cache
+
+Resolved `git remote` → module lookups are cached at
+`<config dir>/qore/cache/repos.json` so repeat commands in the same
+repository skip an extra request. It's pure cache — deleting the file is
+always harmless, at worst the next command re-resolves.
+
+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
@@ -49,8 +271,8 @@ qore whoami --json
 | Code | Meaning |
 |------|---------|
 | 0 | Success |
-| 1 | Internal error, or the OS keychain is unavailable/access was denied |
-| 2 | Missing or invalid context (e.g. a bad `--portal` value) |
+| 1 | Internal error, `git` is not installed or not on `PATH`, or the OS keychain is unavailable/access was denied |
+| 2 | Missing or invalid context (e.g. a bad `--portal` value, or no module selected), or the module is part of several apps and no `--app` was given |
 | 4 | Not logged in, session/login expired, login denied, or clock skew |
 | 5 | Access denied — lost tenant access, resource not found, no developer access |
 | 6 | Auth or API temporarily unreachable/unavailable |