@quatronic/qore 0.1.2 → 0.1.4

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.
 
@@ -255,6 +380,95 @@ qore sync --pull              # ...and fast-forward every clean repository with
   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.
+
+**Feedback.** Before anything starts, a module not yet cloned is offered as
+`Clone <module>, <module> now with qore sync? [Y/n]` (a TTY only, never
+with `--json`/`--no-input`; `--yes` does not accept it). A module sync
+cannot clone (a conflicting directory, no repository yet, an unsupported
+repository URL, GitHub not linked, no repository access) gets its own
+warning naming the real next step, and no prompt. While preflight runs, one progress line per
+module per step (package manager, install, env, ports) is printed as it
+completes. Once every module with a port is either listening or has been
+reported as not running, a one-line summary follows: `✔ All modules
+running:` (or `✔ Running:` / `! Not running:` when some were skipped) lists
+each module with its URL or its reason. A module that crashes while others
+keep running gets a restart hint
+(`Restart it on its own: qore dev --only <module>`, in another terminal;
+the others keep running); on shutdown, a final
+line lists what stopped cleanly and what crashed, with how long it ran.
+When the failure is about the developer's machine rather than the app
+(Docker, Node version, a port busy with something other than a previous
+`qore dev`, a package manager), the error is followed by a pointer to
+`qore doctor` for a full check.
+
+**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
@@ -271,8 +485,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 |