@quatronic/qore 0.1.0 → 0.1.1

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,146 @@ 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`.
+
 ### `--json`
 
 Every command accepts `--json`, which prints exactly one JSON document on
@@ -49,8 +192,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 |