dotbot/controller_app: offer to scaffold a simulator world file

AI-assisted: Claude Opus 4.8

Author: geonnave

dotbot/controller_app.py

@@ -9,7 +9,9 @@
 
 import asyncio
 import os
+import shutil
 import sys
+from pathlib import Path
 
 import click
 import serial
@@ -90,6 +92,46 @@ def _conn_to_settings(conn, swarm_id, sim_is_dotbot):
     return {"adapter": "dotbot-simulator" if sim_is_dotbot else "sailbot-simulator"}
 
 
+def _maybe_scaffold_sim_state(explicit_init_state):
+    """Offer to drop an editable example world in the current directory.
+
+    `explicit_init_state` is the path set via `--simulator-init-state` or
+    the config file, or None when unspecified (the default world). Fires
+    only when nothing was specified and no `simulator_init_state.toml` is
+    here. An interactive run gets a [Y/n] prompt; declining — or a
+    non-interactive run (CI, a pipe) — leaves the cwd untouched and the
+    simulator falls back to the packaged world, so it always starts.
+    Writing the file lets the operator edit the simulated swarm
+    (positions, count, Mari vs default mode).
+    """
+    if explicit_init_state is not None:
+        return  # a path was set via --simulator-init-state or config
+    if Path(SIMULATOR_INIT_STATE_DEFAULT).is_file():
+        return  # a cwd file already exists; it'll be used as-is
+    if not sys.stdin.isatty():
+        return  # non-interactive: silently use the packaged default
+
+    target = Path.cwd() / SIMULATOR_INIT_STATE_DEFAULT
+    if not click.confirm(
+        f"No {SIMULATOR_INIT_STATE_DEFAULT} in this directory. "
+        "Create an editable example here?",
+        default=True,
+    ):
+        return
+
+    from dotbot.dotbot_simulator import packaged_init_state_path
+
+    try:
+        shutil.copy(packaged_init_state_path(), target)
+    except OSError as exc:
+        click.echo(
+            f"Could not write {target}: {exc}; using the built-in world.",
+            err=True,
+        )
+        return
+    click.echo(f"Created {target} — edit it to customize the simulated swarm.")
+
+
 @click.command()
 @click.option(
     "-n",
@@ -229,6 +271,15 @@ def main(
     # implementation detail — the CLI never exposes it.
     conn_settings = _conn_to_settings(conn, swarm_id, sim_is_dotbot)
 
+    # For a simulator connection with no init-state set (CLI default is
+    # None, so fold in any config value), offer to scaffold an editable
+    # world file in the cwd. resolve_init_state_path then picks up the
+    # freshly-written file (or the packaged world if declined/non-tty).
+    if conn_settings.get("adapter", "").endswith("simulator"):
+        _maybe_scaffold_sim_state(
+            simulator_init_state or file_data.get("simulator_init_state")
+        )
+
     cli_args = {
         "gw_address": gw_address,
         "controller_http_port": controller_http_port,

dotbot/tests/test_controller_app.py

@@ -121,3 +121,63 @@ def test_main_warns_on_legacy_config_keys(controller, _, tmp_path):
     # conn=simulator wins; the stale adapter/mqtt_host are ignored.
     assert settings.adapter == "dotbot-simulator"
     assert settings.mqtt_host != "stale"
+
+
+def test_scaffold_sim_state_creates_example_when_accepted(tmp_path, monkeypatch):
+    """Interactive simulator run with nothing specified + `y` writes an
+    editable `simulator_init_state.toml` in the cwd."""
+    from dotbot import SIMULATOR_INIT_STATE_DEFAULT
+    from dotbot.controller_app import _maybe_scaffold_sim_state
+
+    monkeypatch.chdir(tmp_path)
+    with patch("sys.stdin") as stdin, patch("click.confirm", return_value=True):
+        stdin.isatty.return_value = True
+        _maybe_scaffold_sim_state(None)  # the value main() passes by default
+    created = tmp_path / SIMULATOR_INIT_STATE_DEFAULT
+    assert created.is_file()
+    assert "[[dotbots]]" in created.read_text()
+
+
+def test_scaffold_sim_state_declined_writes_nothing(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    from dotbot import SIMULATOR_INIT_STATE_DEFAULT
+    from dotbot.controller_app import _maybe_scaffold_sim_state
+
+    with patch("sys.stdin") as stdin, patch("click.confirm", return_value=False):
+        stdin.isatty.return_value = True
+        _maybe_scaffold_sim_state(None)
+    assert not (tmp_path / SIMULATOR_INIT_STATE_DEFAULT).exists()
+
+
+def test_scaffold_sim_state_noninteractive_never_prompts(tmp_path, monkeypatch):
+    """No TTY (CI, a pipe) → no prompt, no file; the packaged world is used."""
+    monkeypatch.chdir(tmp_path)
+    from dotbot import SIMULATOR_INIT_STATE_DEFAULT
+    from dotbot.controller_app import _maybe_scaffold_sim_state
+
+    with patch("sys.stdin") as stdin, patch("click.confirm") as confirm:
+        stdin.isatty.return_value = False
+        _maybe_scaffold_sim_state(None)
+        confirm.assert_not_called()
+    assert not (tmp_path / SIMULATOR_INIT_STATE_DEFAULT).exists()
+
+
+def test_scaffold_sim_state_skips_when_explicit_path_given(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    from dotbot.controller_app import _maybe_scaffold_sim_state
+
+    with patch("sys.stdin") as stdin, patch("click.confirm") as confirm:
+        stdin.isatty.return_value = True
+        _maybe_scaffold_sim_state("my_world.toml")  # explicit path → no prompt
+        confirm.assert_not_called()
+
+
+@patch("dotbot_utils.serial_interface.serial.Serial.open")
+@patch("dotbot.controller.Controller.run")
+@patch("dotbot.controller_app._maybe_scaffold_sim_state")
+def test_main_simulator_offers_scaffold_with_none(scaffold, _run, _serial):
+    """Regression: `--conn simulator` with no flag/config must reach the
+    scaffold with None (the option default), not a sentinel string."""
+    runner = CliRunner()
+    runner.invoke(main, ["--conn", "simulator"])
+    scaffold.assert_called_once_with(None)