@quatronic/qore 0.1.1 → 0.1.3

package/README.md

@@ -140,20 +140,145 @@ qore run -- pnpm dev
   no worse than a `.env.local` on disk, but worth knowing before running an
   untrusted command this way.
 
+#### `qore dev`
+
+Starts this module's dev server, from a trusted repository:
+
+```sh
+qore dev
+```
+
+- **Context + trust**, like `qore run`/`qore env pull` — the same
+  `--module`/`--app` resolution, the same trust-on-first-use prompt
+  (`--yes` to skip it non-interactively).
+- **Install**, if needed: the package manager comes from package.json's
+  `"packageManager": "<pnpm|npm|yarn>@<version>"` field, or (absent that)
+  whichever lockfile is present. `node_modules` missing, or older than the
+  lockfile, triggers an install; `--no-install` skips this step entirely.
+- **Env merge**: this module's local secrets are pulled and merged into its
+  env file on disk (same target and conflict rules as `qore env pull`) —
+  unlike `qore run`, which only injects them into the child's environment.
+- **`db:up`**, if the repository declares one: run automatically (unless
+  `--no-services`), then `qore dev` waits for `DB_PORT` to accept
+  connections before continuing — bounded by `--wait-timeout <s>` (default
+  `60`), which also bounds a workspace's provider-port wait (below). A
+  service that needs Docker and finds it missing or not running fails
+  fast, naming which.
+- **Port check**: `PORT` from the merged env must be free; qore never
+  picks, shifts or suggests a port (see "Ports never move" below).
+- **Runs `dev` exactly as `qore run` would** — same package manager, same
+  child-process semantics, same exit-code passthrough. The script name is
+  `"dev"` by default, or `dev.script` in `.qore.json` (below).
+- `qore dev` in a module repository has no `--json`: the dev server's own
+  output passes straight through untouched.
+
+A legacy backend `dev` script (from older templates, which need a
+build and a `.env` first) fails fast with `QORE_DEV_UNSUPPORTED`, naming
+the old script and the fix — the same code a repository with no `dev`
+script at all, or an unsupported package manager, gets.
+
+**Offline start**: if the portal is unreachable, `qore dev`
+still starts — but only when the repository is already trusted **and** its
+env file already exists on disk (from a previous `qore dev`/`env pull`).
+It starts from that file as last written, with a warning that values may
+be stale. This is the one place `qore` starts without confirming secrets
+are current; every other command still requires the portal. An untrusted
+repository, or one with no env file yet, surfaces the original
+"portal unreachable" error instead.
+
+**In a workspace root** (see "Workspaces" below), `qore dev` starts every
+present module of the app, in dependency order, from one process — unless
+`--module <slug>` is passed, which takes the module flow above instead
+(run it from inside that module's own repository, not the workspace root
+itself, or it fails with "Not inside a module repository"). `--app` is
+refused in a workspace root: an app is already implied by
+`qore.workspace.json`.
+
+**Ports never move.** If `PORT` (or, for a workspace, a `db:up`'s
+`DB_PORT`) is already taken, `qore dev` fails with `QORE_PORT_IN_USE`
+naming the port and, when it can determine one, the process already
+holding it — it never picks a different port, shifts one, or suggests an
+alternative. Ports are part of the local contract between modules
+(`CONN_*_URL` values point at fixed ports), so moving one silently would
+break every other module that depends on it.
+
+#### What qore diagnoses
+
+Beyond the checks above, `qore dev` recognises common failure shapes and adds
+a hint rather than leaving a bare error (spec §14.2):
+
+- **Docker not running**: in a TTY, waits up to 120 s for it (`Ctrl+C` to
+  stop) instead of failing immediately; non-interactive or `--json` fails at
+  once.
+- **A leftover `qore dev` holds the port**: in a TTY, offers to stop it
+  (`Stop the previous qore dev (pid N)?`); outside a TTY it's just
+  `QORE_PORT_IN_USE`.
+- **The dev server exits within seconds of starting**: its tail output is
+  classified into a hint — a missing dependency (`Cannot find module`), an
+  invalid/missing env var (a `ZodError`'s keys, never values), a port taken
+  after the free-port check (`EADDRINUSE`), or a Linux file-watcher limit —
+  printed after the exit, never rewriting the server's own output. An
+  unrecognised failure falls back to the tool's last lines plus the command
+  that ran, never a bare "failed".
+- **The portal is unreachable behind a corporate proxy**: the connect error
+  names `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` as things to check.
+
+`QORE_DEV_EXITED` is not a thrown code: when none of this applies, `qore dev`
+just passes the child process's own exit code through.
+
+#### `qore doctor`
+
+Runs the same checks `qore` makes before other commands, on demand, without
+doing anything else — the first thing to run when something's wrong, and
+`--json` makes it attachable to a support ticket:
+
+```sh
+qore doctor
+```
+
+- Prints one line per check: `✓` ok, `!` warning, `✗` failing.
+- Checks qore's own version, Node, git, GitHub SSH, Docker + compose, every
+  logged-in portal's session, clock skew, and — inside a workspace or module
+  repository — each module's port, access and database.
+- **Never fetches the local env and never starts anything.** Ports are read
+  from the env file already on disk; access comes from the ordinary
+  `GET /api/cli/v1/me` and `.../modules` routes.
+- Exit code `0` only when every check passes; a `!` warning never fails it,
+  only a `✗` does.
+- No login profile at all is a warning, not a failure.
+- `--json` shape: success is `{"ok":true,"data":{"results":[...],"context":{...}}}`;
+  on failure it's `{"ok":false,"error":{...,"details":{"results":[...],"context":{...}}}}`
+  — the full report is always in `details`, even though the top-level error
+  names only the first failing check. A check that throws still lets the
+  rest run; it just becomes a `fail` with that error attached.
+
 #### `.qore.json`
 
 An optional file at the repository root that configures `qore env pull`
-for that repository. Schema:
+and `qore dev` 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"]
+  "localSecrets": ["MY_LOCAL_OVERRIDE"],
+  "dev": {
+    "install": true,
+    "services": ["db:up"],
+    "script": "dev"
+  }
 }
 ```
 
+- **`dev.install`** — run the package manager's install when needed
+  (default `true`).
+- **`dev.services`** — package.json scripts to run before the dev server,
+  in order (default: `["db:up"]` if that script exists, else none — each
+  name must be a real script in package.json).
+- **`dev.script`** — the package.json script `qore dev` runs (default
+  `"dev"`).
+
 It never holds a portal URL, tenant, app or module id — those are always
 resolved from the git remote or `--module`/`--app`, never committed.
 
@@ -176,6 +301,154 @@ 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.
+
+#### `qore dev` (workspace root)
+
+Run from the directory holding `qore.workspace.json` (not inside one of its
+module repositories — that takes the single-module flow above), starts
+every present module of the app as one supervised run:
+
+```sh
+qore dev                      # every present, writable module, in dependency order
+qore dev --only api,web       # just these (comma-separated)
+qore dev --skip docs          # all but these
+qore dev --kill-others        # the first module to exit stops the rest
+```
+
+- Only **present** modules run (cloned into the workspace); one not cloned
+  yet is skipped with "not cloned — run `qore sync`". A module without
+  write access is skipped too (local secrets need write) naming who to
+  ask; its dependents still start, with a warning that the dependency
+  they point at (`CONN_*_URL`) won't be running — qore never falls back to
+  staging. `--only`/`--skip` select by slug; a skip is never fatal by
+  itself, only when it leaves nothing to start.
+- **Every module's install, package-manager check and port check run
+  first, for every module, before anything starts.** Problems are
+  collected per module and all reported together — one module's install
+  failure never hides another's, and nothing starts if any of them failed.
+  Installs run with bounded parallelism (4 at a time).
+- **Start order follows `dependsOn`**: providers before their consumers.
+  A consumer waits (up to `--wait-timeout`, default `60` s) for each
+  dependency's `PORT` to accept connections before its own `dev` script
+  runs; a dependency that doesn't come up in time (or that exited) logs a
+  warning and the consumer starts anyway. Modules that depend on each
+  other (a cycle) start together, without waiting, and the cycle is
+  reported once. A backend under `node --watch` that crashes waits for a
+  file change instead of exiting, so no exit line appears and its
+  consumers wait up to `--wait-timeout`.
+- **`--kill-others`**: the first module to exit on its own (success or
+  failure) stops every other module; the others' own exit is then reported
+  quietly, not as a failure. Without it, `qore dev` keeps every surviving
+  module running until you stop it yourself.
+- **Ctrl+C / SIGTERM/SIGHUP** stops every running module in reverse start
+  order, `SIGKILL` after a 10 s grace if one doesn't exit on its own; a
+  second Ctrl+C escalates to `SIGKILL` immediately. A `db:up` service a
+  module started is left running — `qore dev` only stops the dev servers
+  it launched directly. During the checks, Ctrl+C / SIGTERM / SIGHUP
+  stops a running install or `db:up` before `qore dev` exits.
+- **Offline start** (same rule as module-level): only when every
+  module that would start is already trusted and has an env file on disk;
+  one exception fails the whole run with the original error.
+
+**Output.** Every line of a dev server's own stdout/stderr is prefixed per
+module and column-aligned:
+
+```
+api │ listening on 8000
+web │ listening on 3001
+```
+
+qore's own start, ready and exit lines (`▶ api (pid 4121)`,
+`✓ api is listening on 8000`, `✗ web exited with code 1`) are not prefixed
+and go to stderr, so `--json`'s stdout stays pure NDJSON. A module's own
+stdout goes to stdout and its stderr to stderr. Colour is disabled with `--json`, `--no-color` or `NO_COLOR`.
+
+With `--json` — the only qore command that streams instead of printing one
+document — stdout is newline-delimited JSON, one event object per line
+(`{"type":"start"|"ready"|"line"|"exit"|"warning"|"skip"|...}`), instead of
+the usual single `{"ok":...}` document. An `exit` event carries an optional
+`hint` (`{"hint":"..."}`, the same early-exit hint the human renderer prints
+as `  → ...`) when the module crashed early with a non-zero code and no
+signal — never on a signalled or graceful exit.
+
 ### `--json`
 
 Every command accepts `--json`, which prints exactly one JSON document on
@@ -192,8 +465,8 @@ qore whoami --json
 | Code | Meaning |
 |------|---------|
 | 0 | Success |
-| 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 |
+| 1 | Internal error, `git` is not installed or not on `PATH`, the OS keychain is unavailable/access was denied, or qore itself needs a newer Node (`QORE_NODE_VERSION`, checked by `qore doctor`'s own `node` check against qore's own `process.version`); `qore dev`: its package manager isn't installed (`QORE_PACKAGE_MANAGER`), its install failed (`QORE_INSTALL_FAILED`), Docker is missing (`QORE_DOCKER_MISSING`), not running (`QORE_DOCKER_NOT_RUNNING`) or its compose v2 plugin is missing (`QORE_DOCKER_COMPOSE_MISSING`), a `db:up`/service failed, never became healthy (`QORE_SERVICE_UNHEALTHY`) or its data is incompatible (`QORE_SERVICE_DATA_INCOMPATIBLE`), or the repository's own `engines.node` doesn't match the `node` on `PATH` (`QORE_NODE_VERSION`, a different check from qore's own — `qore doctor`'s `node:<module>` check, run only in a trusted repository) |
+| 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; `qore dev`: a port is already in use (`QORE_PORT_IN_USE`) or the repository's dev setup isn't supported (`QORE_DEV_UNSUPPORTED`) |
 | 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 |