Finalize `watch` command and documentation

[lbroudoux]

Reason/Context

We need to progress on the next version of CLI and improve some stuff regarding the watcher behavior. The primary goal is to be able to launch the watcher from the command line, using the same binary.

Description

I checked the import command and saw there's already a --watch flag. At first, I thought it was the right place to launch the watcher but I saw that this just updates the watcher configuration file.

I wonder:

1. Should we keep that this way and have another command like microcks watch that starts the watcher in the foreground until we Ctrl+C it ?
2. Should we just launch the watcher on presence of this flag in the microcks import command (here again, waiting for the Ctrl+C signal)

Also, I saw that each entry in the watcher configuration file has a list of contexts attached. Launching the watcher externally (as a separate command) means that without context, the watcher cannot find the correct Microcks instance to push local changes to...

Maybe then: we should be able to handle both case? Launching the watcher with the import - in that case, it reuses the current context + launching the watcher independently - in that case, it uses the context configured in the wath config file.

What do you think @Harsh4902?

Implementation ideas

No response

[Harsh4902]

@lbroudoux Totally agree. Give me some time, I'll come back with the solution. Currently, I'm a bit occupied.

[Caesarsage]

i think we can go with the hybrid approach where the import --watch run the actual watcher as its more user intuitive and we can also have another standalone command @lbroudoux @Harsh4902

[lbroudoux]

I spent some time yesterday on this, and I got it working, and I needed to do some refactoring.

The trickiest thing I didn't notice before was that the watcher was bound to the concept of context and configuration file. However, I think we should also be able to use it without any configuration file and pre-existing context in the use case we're using an instance that has not been started by the CLI.

So I'm currently working on this part and I hope to have something soon.

[lbroudoux]

Working fine!

This is the scenario I have tested:

1. Launch a regular Microcks instance: docker run -p 8585:8080 -p 8686:9090 -it --rm quay.io/microcks/microcks-uber:nightly-native

2. Issue the import command with the new flag:

$ go run main.go import ./samples/weather-forecast-openapi.yml:true,./samples/weather-forecast-postman.json:false --microcksURL=http://localhost:8585 --keycloakClientId=foo --keycloakClientSecret=bar --watch
---- OUTPUT ---- 
Microcks has discovered 'WeatherForecast API:1.1.0'
Microcks has completed 'WeatherForecast API:1.1.0'
2025/11/28 11:50:27 [INFO] Watcher added on samples/weather-forecast-openapi.yml
2025/11/28 11:50:27 [INFO] Watcher added on samples/weather-forecast-postman.json
Watch mode enabled - microcks-watcher started...

The watcher is running and waiting for changes. The files to watch are persisted into a local ~/.config/microcks/watch file:

entries:
- filePath: samples/weather-forecast-openapi.yml
  context:
  - http://localhost:8585
  mainartifact: true
- filePath: samples/weather-forecast-postman.json
  context:
  - http://localhost:8585
  mainartifact: false

You can notice by the way that we removed the ./ prefix, otherwise the path name doesn't match the one that is provided by the fsnotify events path names.

3. When editing the postman collection in my IDE and saving the file, we can see these new lines on console:

[INFO] Re-importing changed file: samples/weather-forecast-postman.json
[INFO] Successfully re-imported samples/weather-forecast-postman.json in context 'http://localhost:8585'

4. Now we can Ctrl+C the current console and watch an independent watcher process:

$ go run watcher/main.go
---- OUTPUT ---- 
2025/11/28 11:55:27 [INFO] Watcher added on samples/weather-forecast-openapi.yml
2025/11/28 11:55:27 [INFO] Watcher added on samples/weather-forecast-postman.json
[INFO] microcks-watcher started...

We'll have the same behavior, watching and updating the files!