@whoz-oss/coday-web 0.0.0-workstream-setup.2 → 0.0.0-workstream-setup.3

package/README.md

@@ -9,7 +9,13 @@ the Express server, and runs AgentOS and the Factory next to them.
 npx @whoz-oss/coday-web
 ```
 
-The first time, the browser opens on **`/welcome`** (`http://localhost:3000/welcome`), a four-step wizard:
+In a terminal (Nx mode, see below) the browser opens by itself. On a **first run** it opens the wizard immediately,
+on **`/welcome`** (`http://localhost:3000/welcome`): the wizard only talks to Coday's own server, so it does not wait
+for AgentOS. Otherwise (setup done) it opens `/` **once AgentOS is healthy**, because the app calls AgentOS straight
+away and would show a blank page until then; if AgentOS never becomes healthy (about 3 minutes: Java missing,
+download failed...) nothing is opened and the `server` pane prints the URL to open yourself. Pass `--no-open` or set
+`CODAY_NO_OPEN=1` to keep it closed. Without a terminal (`--managed`, desktop apps) nothing is opened: open the URL
+printed as `Server is running on http://localhost:PORT` yourself. The wizard is a four-step flow:
 
 1. **Your email.** It becomes your user ID and the AgentOS administrator. AgentOS and Factory JARs start downloading in
    the background as soon as the page is open.
@@ -37,22 +43,43 @@ otherwise the app opens directly.
   ────────────────────                          ───────────────────────────────────
   coday-web (index.js)                          coday-web (index.js)
     └─ writes <configDir>/runtime/{nx,project}.json
-    └─ nx run-many -t server agentos factory    └─ one process: Express + AgentOS + Factory
-         provision ─┬─ server    (pane 1)           (what the desktop apps use; prints
-                    ├─ agentos   (pane 2)            `Server is running on http://localhost:PORT`)
-                    └─ factory   (pane 3)
+    └─ nx run coday:status                     └─ one process: Express + AgentOS + Factory
+         provision ─┬─ status   (entry task)        (what the desktop apps use; prints
+                    │    ├─ server   (pinned next    `Server is running on http://localhost:PORT`)
+                    │    │            to status,
+                    │    │            opens the browser)
+                    │    ├─ agentos  (own pane)
+                    │    └─ factory  (own pane)
 ```
 
 - **Nx mode** (default in a terminal). The launcher generates a tiny Nx workspace under `<configDir>/runtime/`
   (no daemon, no cloud, no cache) and runs the bundled `nx`. `provision` is a quick task (profile, secrets, Java check,
-  ports → `runtime/state.json`); `server`, `agentos` and `factory` are continuous tasks, each with its own pane. `agentos`
-  prints *Waiting for first-run setup → http://localhost:3000/welcome* until you gave your email; `factory` waits for
-  AgentOS to be healthy.
+  ports → `runtime/state.json`); `status`, `server`, `agentos` and `factory` are continuous tasks, each with its own
+  pane. The launcher runs ONE target, `nx run coday:status`, and `status` depends on the three services, so Nx starts
+  them for it. `agentos` prints *Waiting for first-run setup → http://localhost:3000/welcome* until you gave your email;
+  `factory` waits for AgentOS to be healthy. Once Express listens, the `server` task opens the browser (see
+  *First run* for when); it never does when `--auth`, a non-loopback `--host`, `CI`, `--no-open` or `CODAY_NO_OPEN` say
+  so. The wait for AgentOS runs beside the server and never delays it or its shutdown. For an external AgentOS
+  (`AGENTOS_URL`) it probes that URL's `/management/health`, which is what the proxy targets.
+- **The `status` pane.** The Nx TUI has no status bar, so a small dedicated task reads `runtime/state.json` and probes
+  the health URLs every second. It prints one line per meaningful change only: `agentos download 42%` (one line per
+  10%), `java ok` or the install hint, `agentos healthy :8124`, `factory healthy :8141`, `agentos external <origin>`
+  for an `AGENTOS_URL`/`FACTORY_URL`, and `Open -> http://localhost:3000/welcome` on a first run (`/` once the setup is
+  done; then the line says `(once agentos is healthy)` and is repeated without that note when it is: same rule as
+  the browser). In the
+  TUI, select a pane and pin it next to another one to keep the download and the URL on screen while you read the
+  logs of the others; press `?` for the key help of the Nx TUI. At startup `status` is pinned next to `server`: Nx
+  pins the initiating task and its first continuous dependency, but only for a single-target run (`nx run`), which is
+  why the launcher does not use `run-many`. That behaviour was derived from reading the Nx 23 sources (the native
+  TUI rendering of pinned panes could not be inspected): confirm it visually.
+  Because `status` depends on the services, none of them may exit while it runs (Nx would report an exited
+  dependency as crashed, and a failed one would skip `status`): a service that cannot start (no Java, download
+  failed, port taken) or that is external (`AGENTOS_URL`/`FACTORY_URL`) prints why and stays open until Ctrl+C.
 - **Managed mode** (no TTY, `--managed`, or `CODAY_NO_NX=1`). Same code, one process, no Nx. The desktop apps spawn
   `coday-web` without a terminal and keep working unchanged.
 
 All the logic lives in the server package (`apps/server/src/lib/runtime`, `lib/setup`); the Nx workspace is only a
-manifest calling `coday-server provision|agentos|factory|server`.
+manifest calling `coday-server provision|agentos|factory|server|status`.
 
 ### Logs
 
@@ -85,6 +112,7 @@ existing installs without a wizard identity keep their previous behaviour: no wi
 | `--configDir <dir>` | Config directory (default `~/.coday`) |
 | `--host <addr>` / `CODAY_HOST` | Interface Express listens on (default `127.0.0.1`; `0.0.0.0` with `--auth`) |
 | `--managed` / `CODAY_NO_NX=1` | Force the single-process mode (no Nx) |
+| `--no-open` / `CODAY_NO_OPEN=1` | Do not open the browser on start (only Nx mode opens it; never with `--auth`, a non-loopback host or `CI`) |
 | `PORT` | Express port (strict when set; default 3000, 4100 in dev) |
 | `AGENTOS_URL`, `FACTORY_URL` | Use an external AgentOS / Factory instead of managed ones |
 | `AGENTOS_EXTERNAL_USERID` | Impose the identity forwarded to AgentOS (disables the wizard) |
@@ -102,6 +130,7 @@ is:
 pnpm nx run web:local                     # everyday: build local code, run it like an npx user, keeps your setup
 pnpm nx run web:local -- --fresh          # test the first-run wizard again (deletes the local config first)
 pnpm nx run web:local -- --managed        # single process, plain console (instead of the Nx TUI)
+pnpm nx run web:local -- --no-open        # do not open the browser (every restart would otherwise open a tab)
 pnpm nx run web:local -- --port 3100      # pick the port
 ```
 
@@ -128,6 +157,7 @@ lies in, them, your home or the repository), and nothing is published.
 |---|---|
 | `--fresh` | Delete `config/` and `files/` (printed) before starting: a brand-new first run |
 | `--managed`, `--port <n>` | Single-process mode, Express port |
+| `--no-open` | Do not open the browser (also `CODAY_NO_OPEN=1`) |
 | `--prepare-only` | Prepare everything, print the paths as JSON on the last line, no server |
 | `--clean` | Delete the **whole** root when the server stops (setup and data included) |
 | `CODAY_LOCAL_DIR=<dir>` | Use another root than `~/.coday-local` (`CODAY_FIRST_RUN_DIR` is a deprecated alias) |
@@ -179,6 +209,11 @@ than the former thin launcher. Versions of the `platform:npm` packages move in l
 - **"Could not resolve @whoz-oss/coday-client package"**: the client is not built or installed. `pnpm install` and
   `pnpm nx run client:build`, or use `pnpm web:serve:dev`.
 - **The Nx panes do not show / garbled output**: use `--managed` (or `CODAY_NO_NX=1`) for plain console output.
-- **"Waiting for first-run setup" never ends**: open the URL printed in the pane and answer the wizard.
+- **"Waiting for first-run setup" never ends**: open the URL printed in the pane (or the `Open ->` line of the `status`
+  pane) and answer the wizard.
+- **The browser did not open**: headless Linux or no `xdg-open`, or AgentOS is not healthy yet (the app is only opened
+  once it is); the `server` pane logs one line and the `status` pane shows the URL.
+- **A blank page on `/`**: AgentOS is not up yet (the app waits up to 90 s for it). Look at the `agentos` pane / log,
+  Java 25 is the usual cause.
 - **Java missing or too old**: install Java 25 (the wizard shows the command), the page continues by itself.
 - **Port already in use**: `PORT=3100 npx @whoz-oss/coday-web`.

package/launcher.js

@@ -50,9 +50,15 @@ export function parseWorkspaceDir(stdout) {
   return dir || undefined;
 }
 
-/** Arguments of `nx run-many` for the three continuous tasks (each gets its own TUI pane). */
+/**
+ * Arguments of `nx run`: ONE target, `coday:status`, whose continuous dependencies are the server, AgentOS and the
+ * Factory (each gets its own TUI pane). A single-target run makes the Nx TUI pin the initiating task (`status`) and
+ * its first continuous dependency (`server`) at startup; `run-many` pins nothing. The target names are those of
+ * NX_ENTRY_TASK / NX_SERVICES in apps/server/src/lib/runtime/workspace.ts (a server spec checks they match).
+ * `--parallel` only caps discrete tasks (`provision`): continuous tasks have their own threads.
+ */
 export function nxArgs() {
-  return ['run-many', '-t', 'server', 'agentos', 'factory', '-p', 'coday', '--parallel=5', '--outputStyle=tui'];
+  return ['run', 'coday:status', '--parallel=5', '--outputStyle=tui'];
 }
 
 /** Environment of the Nx process: no daemon, no cloud, no cache. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whoz-oss/coday-web",
-  "version": "0.0.0-workstream-setup.2",
+  "version": "0.0.0-workstream-setup.3",
   "repository": "https://github.com/whoz-oss/coday",
   "type": "module",
   "bin": {
@@ -13,9 +13,9 @@
   ],
   "dependencies": {
     "nx": "23.1.1",
-    "@whoz-oss/coday-client": "0.0.0-workstream-setup.2",
-    "@whoz-oss/coday-factory-cockpit": "0.0.0-workstream-setup.2",
-    "@whoz-oss/coday-server": "0.0.0-workstream-setup.2"
+    "@whoz-oss/coday-factory-cockpit": "0.0.0-workstream-setup.3",
+    "@whoz-oss/coday-client": "0.0.0-workstream-setup.3",
+    "@whoz-oss/coday-server": "0.0.0-workstream-setup.3"
   },
   "publishConfig": {
     "access": "public"