feat: Add interactive registration mode

[knolleary]

This PR overhauls the startup of the Device Agent to provide an interactive setup option.

Notable changes in behaviour:

• It checks the port NR will run on (as set by cli, config or default 1880) - if the port is not available it exits early
• It checks the config dir exists and is writable - quits if not writeable before doing any config work
• If no config is found to exist, it starts the new interactive setup mode. This prompts the user to get the device registered, or enter a OTC to continue. All of the logging in this mode is without timestamp formatting - because its interactive.
• It no longer asks if you want to start NR once setup is complete. The existing --otc-no-start option can be used in scripts if necessary. Otherwise it just gets on with the job.

I have rearranged the setup code to, hopefully, be fairly logically structured.

The tests have been updated to include the port in-use check.

To fully test this PR requires a FF platform running FlowFuse/flowfuse#7820 to provide UI parts of the interactive registration.

I have spent quality time with Claude reviewing and fixing items it has identified in review.

[Steve-Mcl]

I may well be missing something - is there still a task to do on the go installer?

Assuming yes - but will document my experience as-is right now.

---

From the go installer

From the go installer, I note the process is not streamlined. For example, when running .\flowfuse-device-installer-windows-amd64.exe the first 2 lines state:

One time code has not been provided. The Device Agent automatic configuration is not possible.
Do you want to continue with the installation? (y/N): 

While true (automatic configuration is not possible) it does not encourage me to think that the process will go on to offer the new improved onboarding experience

I answered y and continue,

Installing Node.js 22.23.0...
Installing FlowFuse Device Agent latest version...
FlowFuse Device Agent installed successfully!
Configuring FlowFuse Device Agent...
No OTC (One-Time Code) provided. Automatic configuration is not possible.
You can either:
* 1. Provide a device configuration file now
  2. Install the device agent only (you'll need to configure it manually later)
Please select an option (1-2) [default: 1]:

Choosing option 2 the process continues and upon completion drops to the command line stating:

Configuration completed successfully!
Configuring FlowFuse Device Agent to run as system service...
Installing FlowFuse Device Agent service for windows...

FlowFuse Device Agent installation completed successfully!
Installation complete! The FlowFuse Device Agent has been installed but requires configuration.
To finish setup:
  1. Create a device.yml configuration file in the c:\opt\flowfuse-device directory
  2. Start the Device Agent service
Refer to the documentation for detailed configuration steps and examples.
Once configured, you can return to the FlowFuse platform and start creating Node-RED flows on your device:
https://app.flowfuse.com

Further reading:
  - To learn how to check the service status, visit https://flowfuse.com/docs/device-agent/install/device-agent-installer/#check-the-device-agent-service-status
  - To learn how to manage the service (start, stop, restart), visit https://flowfuse.com/docs/device-agent/install/device-agent-installer/#managing-the-device-agent-service
  - To learn how to view logs, visit https://flowfuse.com/docs/device-agent/install/device-agent-installer/#viewing-device-agent-log-files

I had expected that the go installer would run node index.js so that I could use the new streamlined onboarding? Perhaps I am missing something?

---

Running this branch from node index.js

Continuing on - to try out the changes presented in this PR, I ran from source (e.g. running node index.js [--<opt> <val>]

I tested both "Register as a new instance" and "Connect with an existing One-Time Code (OTC)" from cmd and ps - both working well. Additionally, tested the port-in-use detection. Also working well on Windows,

nits

the removal of try..catch..log (see inline review comment)

Friction points

This is mostly personal opinion and some of it being due to not following golden path but thought I'd mention them anyhow since this PR is about improving onboarding.

Dont show "Invalid registration session" page if user elects to CTRL-click the presented link

When setting up a device, the user is presented a URL

Welcome to the FlowFuse Device Agent v4.1.0

Connecting to http://192.168.86.46:3000/

To continue with registering your new instance, press ENTER to open the the following URL in your browser:

 ▸ http://192.168.86.46:3000/register/remote-instance/jXWxazmT9AvmzGIGSCuJaw

# I ctrl-clicked this link ↑ and filled out the web form BEFORE i pressed enter
# After hitting enter, the process continued ↓ (good) - but - the browser still opened and showed "Invalid registration session"

Waiting for registration to complete...

Successfully registered as nick-test-5 (BKv9xpk9bQ) in Team Enterprise Team

The process did complete but it opened a browser page and showed me this:

Not a blocker - but not ideal either.

Lack of --setup or --reset option

For me, there is a possibility of friction when a partial (or old/forgotten) /opt/flowfuse-device/ yml exists.
I found the need to manually clean up /opt/flowfuse-device or provide an alternative --dir to be a sticky point we could easily remove. For example supporting a --reset or --setup option that ignores the existence of a yml file and lets the user succeed without manual intervention would be slick.

NOTE: I recognise the go installer can (and does) detect presence of old config and offers clean up - this is great for golden path but not so great for anyone not using the installer method.

Not a blocker - a convenience / life improvement thing

Unable to provide name of new device in CLI

A very minor friction point is that I cannot provide the name or type info in the CLI
Ideally, after I chose "Register as a new instance" it would be great if the name could be specified and caried through.

Not a blocker - very much a nice to have!

[knolleary]

@Steve-Mcl I am working on the installer updates at the moment. This PR is just on the device agent setup part of it.

Dont show "Invalid registration session" page if user elects to CTRL-click the presented link

Will consider how to check the state at the right time to handle that. It would need to start polling the done url before even trying to open the URL to see if the user has jumped the gun on it.

Lack of --setup or --reset option
Unable to provide name of new device in CLI

Both good suggestions, but not in scope for this PR. We're very much focussed on first-run experience, and keeping the cli simple to use by default.

[knolleary]

@Steve-Mcl this is ready for final review.

It no longer shows the URL at the 'hit enter to open your browser' prompt. The user has to hit enter and then we show the URL if they need to manually access it. That solves the jump-the-gun scenario.

I have raised a separate PR for the minimal install updates - #708 - that can merge after this one has as its a separate release.

[Steve-Mcl]

As discussed on slack, I have pushed commit c7e29aa which adds an additional pause

Successfully registered as XX in Team YY

Press ENTER to continue... (this disappears upon receiving an ENTER)

We have found existing Node-RED flows. Do you want to import these into your new instance?

so that the user isnt sitting there pressing UP/DOWN with nothing happening - thinking it is locked up.

It also acts a guard to swallow an ENTER in the buffer.

[Steve-Mcl]

Tested locally (extensively) - all good bar the issue discussed on slack and mitigated in c7e29aa