feat(plugin-dev): add watch mode, readiness polling, and phased start UX

AGENTS.md

@@ -125,6 +125,13 @@ registered in `src/commands/index.ts` and lazy-load their handlers from
 re-staging) — use it when changing RHDH Local configuration without touching
 plugin code. `update` re-exports, re-stages, and then restarts the RHDH service.
 
+`start` and `update` both block on `waitForRhdhReady` (poll-based, 120s default
+timeout) before returning, printing the RHDH URL once it responds. Both also
+accept `--watch`, which hands off into `watchUpdate`: a chokidar watcher on
+`src/`, `package.json`, and `tsconfig.json` (500ms debounce, serialized cycles) that repeats the
+same export/stage/restart cycle as a one-shot `update` on every source change,
+so a source edit doesn't require re-running the command by hand.
+
 Key files:
 
 - `command.ts` — per-subcommand handlers (`start`, `update`, `restart`, `stop`,
@@ -152,7 +159,11 @@ RHDH Local and will not appear in `git status` after a successful `start`.
 **Pre-flight check:** `start` and `update` call `validateProjectFiles()` before
 invoking `plugin export`. For backend plugins this checks that `dist-types/`
 exists, failing fast with a clear `yarn tsc` instruction rather than letting
-`yarn build` fail deep in the export process.
+`yarn build` fail deep in the export process. `update` and `restart` also call
+`ensureRuntimeRunning()` first, which inspects Compose `ps` for the `rhdh`
+service and fails fast with an actionable message ("RHDH Local is not running.
+Run `rhdh-cli plugin dev start` first.") instead of a raw compose/container
+subprocess error.
 
 **Symlink handling:** `stagePlugin` uses `fs.remove` + `fs.copy` with
 `dereference: false` so relative symlinks in `node_modules/.bin/` are preserved

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- **`plugin dev`:** Add `--watch` to `rhdh-cli plugin dev start`, and a standalone `rhdh-cli plugin dev update --watch`, for continuous re-export/re-stage/restart on source changes ([RHIDP-16673](https://redhat.atlassian.net/browse/RHIDP-16673), [#222](https://github.com/redhat-developer/rhdh-cli/pull/222)). Watches `src/`, `package.json`, `tsconfig.json` with a 500ms debounce and serializes cycles so a change arriving mid-cycle queues exactly one follow-up; prints a refresh URL once RHDH responds. `plugin dev start` now also shows phased `[1/4]`–`[4/4]` progress through build/export, runtime start, plugin install, and readiness polling. `plugin dev update` and `plugin dev restart` fail fast with an actionable message when RHDH Local isn't running yet, instead of surfacing a raw compose/container error.
+
 ## 2.1.1 - 2026-09-21
 
 ### Added

README.md

@@ -88,12 +88,24 @@ Use `plugin dev` from a generated or existing dynamic plugin project to export i
 rhdh-cli plugin dev start --configure --rhdh-local-dir /path/to/rhdh-local
 ```
 
-`--configure` adds the CLI-managed plugin configuration include without replacing existing user configuration. Set `RHDH_LOCAL_DIR` to avoid repeating the path. After changing plugin source, refresh the staged plugin and RHDH service with:
+`--configure` adds the CLI-managed plugin configuration include without replacing existing user configuration. Set `RHDH_LOCAL_DIR` to avoid repeating the path. `start` prints four labeled phases (`[1/4]` build/export, `[2/4]` start the runtime, `[3/4]` install plugins, `[4/4]` wait for readiness) and blocks until RHDH responds, printing the URL to open once it's ready.
+
+After changing plugin source, refresh the staged plugin and RHDH service with:
 
 ```bash
 rhdh-cli plugin dev update
 ```
 
+`update` and `restart` require the runtime to already be running — start it first with `plugin dev start`, or they fail fast with an actionable message instead of a raw compose/container error. Like `start`, `update` blocks until RHDH is reachable again (up to two minutes) and prints the URL on success.
+
+Pass `--watch` to `start` or `update` to keep the CLI running: it watches `src/`, `package.json`, and `tsconfig.json` and automatically re-exports, re-stages, and restarts the runtime on every change, so you don't have to re-run `update` by hand.
+
+```bash
+rhdh-cli plugin dev start --watch
+# or, once the runtime is already up:
+rhdh-cli plugin dev update --watch
+```
+
 Use `rhdh-cli plugin dev status` for the interpreted runtime state, `rhdh-cli plugin dev logs` for application logs, and `rhdh-cli plugin dev logs --installer` to diagnose installation failures. To restart the RHDH service after changing RHDH Local configuration (without re-deploying the plugin), use `rhdh-cli plugin dev restart`. Stop the runtime with `rhdh-cli plugin dev stop`; add `--clean` to remove containers and networks while retaining volumes, configuration, and plugin artifacts. The default container tool is `podman`; pass `--container-tool docker` if your environment uses Docker instead.
 
 The CLI manages a single plugin entry in `configs/dynamic-plugins/rhdh-cli.generated.local.yaml`. Each `start` or `update` run overwrites this file with the current plugin's package path, disabled flag, and pull policy. Extra `pluginConfig` for the plugin (such as app-config keys) belongs in `dynamic-plugins.override.yaml` under a `plugins:` entry for the same package, not in the generated file.

package.json

@@ -56,6 +56,7 @@
     "@yarnpkg/lockfile": "^1.1.0",
     "@yarnpkg/parsers": "^3.0.0-rc.4",
     "chalk": "^4.0.0",
+    "chokidar": "^5.0.0",
     "codeowners": "^5.1.1",
     "commander": "^9.1.0",
     "eslint": "8.57.1",