caffeinated-whale-cli 2.3.0__tar.gz → 2.3.1__tar.gz

{caffeinated_whale_cli-2.3.0 → caffeinated_whale_cli-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caffeinated-whale-cli
-Version: 2.3.0
+Version: 2.3.1
 Summary: A CLI tool to help manage Frappe Docker instances.
 Author-email: Christopher McKay <mckay.christopher73@outlook.com>
 License: MIT
@@ -320,15 +320,19 @@ Then open http://development.localhost:8000 (or `cwcli open my-project`).
 If the dev services fail to start, init still exits successfully (the bench was already created) and prints a warning telling you to run `cwcli start` yourself.
 The start itself waits for the web server to answer on the bench's own configured port before declaring success; if that times out, init reports the same "not running" output even though the containers and supervisor did launch, since the web isn't actually serving yet.
 If the port cannot be read, start skips the wait and warns instead of probing another bench's port.
+If the web server is running inside the container but its port is not published to the host, init prints a warning naming the missing host binding and advises recreating the instance.
 
 **Port Conflict Handling:**
 
-If the requested ports are in use, you'll see:
+Init retries occupied ports five times, one second apart, to allow bindings from a just-removed instance to finish releasing.
+Each retry is announced in both interactive and non-interactive runs.
+If the ports remain occupied, init exits nonzero before creating the instance and names every conflicting port:
 
 ```
 Error: The following ports are already in use: 8000-8005
 
-Tip: Use the --port flag to select a different starting port.
+Tip: If an instance using these ports was just removed, they may still be releasing - wait a few seconds and retry.
+Tip: Otherwise, use the --port flag to select a different starting port.
 Example: cwcli init my-project --port 10000
 ```
 
@@ -498,6 +502,7 @@ cwcli start [OPTIONS] [PROJECT_NAME]...
 - **Idempotent:** a re-run on an already-running bench is a clean no-op ("already running: N/N processes up"), never a second supervisor stack
 - **Per-process supervision:** each Procfile process runs under supervisord, so one can be restarted or auto-healed without disturbing the others
 - **Waits for the web server:** on a genuine launch, `start` blocks until the bench's **own** web port actually answers before reporting the bench as running, so a scripted `cwcli start && cwcli status` never catches a transient `degraded`. The port is read from that bench's `sites/common_site_config.json`, never assumed - waiting on a hardcoded `:8000` meant `--bench 1` watched bench 0's port and then warned that a healthy bench had not started. If the port cannot be read, the wait is **skipped** (`web_ready` stays unset) rather than spent on a guess. A timeout (60s) does not fail the start (the stack IS launched) - it prints a warning naming the real port and telling you to check `cwcli status` / `cwcli logs`
+- **Host port verification:** on both a genuine launch and an idempotent no-op, `start` warns when the bench's web server has no live host port binding. The warning names the container port and advises recreating the instance with `cwcli init`
 - **Port Conflict Detection:** Automatically checks if required ports are available
 - **Interactive Resolution:** Offers to stop conflicting Frappe projects (use `--yes` to auto-confirm)
 - **Process Identification:** Shows which processes are using ports (cross-platform)

{caffeinated_whale_cli-2.3.0 → caffeinated_whale_cli-2.3.1}/README.md

@@ -280,15 +280,19 @@ Then open http://development.localhost:8000 (or `cwcli open my-project`).
 If the dev services fail to start, init still exits successfully (the bench was already created) and prints a warning telling you to run `cwcli start` yourself.
 The start itself waits for the web server to answer on the bench's own configured port before declaring success; if that times out, init reports the same "not running" output even though the containers and supervisor did launch, since the web isn't actually serving yet.
 If the port cannot be read, start skips the wait and warns instead of probing another bench's port.
+If the web server is running inside the container but its port is not published to the host, init prints a warning naming the missing host binding and advises recreating the instance.
 
 **Port Conflict Handling:**
 
-If the requested ports are in use, you'll see:
+Init retries occupied ports five times, one second apart, to allow bindings from a just-removed instance to finish releasing.
+Each retry is announced in both interactive and non-interactive runs.
+If the ports remain occupied, init exits nonzero before creating the instance and names every conflicting port:
 
 ```
 Error: The following ports are already in use: 8000-8005
 
-Tip: Use the --port flag to select a different starting port.
+Tip: If an instance using these ports was just removed, they may still be releasing - wait a few seconds and retry.
+Tip: Otherwise, use the --port flag to select a different starting port.
 Example: cwcli init my-project --port 10000
 ```
 
@@ -458,6 +462,7 @@ cwcli start [OPTIONS] [PROJECT_NAME]...
 - **Idempotent:** a re-run on an already-running bench is a clean no-op ("already running: N/N processes up"), never a second supervisor stack
 - **Per-process supervision:** each Procfile process runs under supervisord, so one can be restarted or auto-healed without disturbing the others
 - **Waits for the web server:** on a genuine launch, `start` blocks until the bench's **own** web port actually answers before reporting the bench as running, so a scripted `cwcli start && cwcli status` never catches a transient `degraded`. The port is read from that bench's `sites/common_site_config.json`, never assumed - waiting on a hardcoded `:8000` meant `--bench 1` watched bench 0's port and then warned that a healthy bench had not started. If the port cannot be read, the wait is **skipped** (`web_ready` stays unset) rather than spent on a guess. A timeout (60s) does not fail the start (the stack IS launched) - it prints a warning naming the real port and telling you to check `cwcli status` / `cwcli logs`
+- **Host port verification:** on both a genuine launch and an idempotent no-op, `start` warns when the bench's web server has no live host port binding. The warning names the container port and advises recreating the instance with `cwcli init`
 - **Port Conflict Detection:** Automatically checks if required ports are available
 - **Interactive Resolution:** Offers to stop conflicting Frappe projects (use `--yes` to auto-confirm)
 - **Process Identification:** Shows which processes are using ports (cross-platform)

{caffeinated_whale_cli-2.3.0 → caffeinated_whale_cli-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "caffeinated-whale-cli"
-version = "2.3.0"
+version = "2.3.1"
 authors = [
   { name = "Christopher McKay", email = "mckay.christopher73@outlook.com" },
 ]

caffeinated_whale_cli-2.3.1/src/caffeinated_whale_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.3.1"

{caffeinated_whale_cli-2.3.0 → caffeinated_whale_cli-2.3.1}/src/caffeinated_whale_cli/commands/axi.py

@@ -2336,7 +2336,7 @@ def axi_init(
             )
         else:
             for warning in start_result.warnings:
-                if warning.code == "start.web_not_ready":
+                if warning.code in ("start.web_not_ready", "start.no_host_port"):
                     print(f"Warning: {warning.text}", file=sys.stderr, flush=True)
 
     emit_result(bench_result.data, warnings=bench_result.warnings)

{caffeinated_whale_cli-2.3.0 → caffeinated_whale_cli-2.3.1}/src/caffeinated_whale_cli/commands/init.py

@@ -173,6 +173,10 @@ class _InitRenderer:
             stderr_console.print(f"[yellow]Warning: {event.text}[/yellow]")
         elif code == "instance.already_running" and self.verbose:
             stderr_console.print(f"[dim]{event.text}[/dim]")
+        elif code == "ports.retry":
+            # Unmissable in both rendering modes: a caller waiting on this run
+            # needs to know it's retrying, not stuck.
+            stderr_console.print(f"[yellow]{event.text}[/yellow]")
 
     def _on_trace(self, event) -> None:
         if not self.verbose:
@@ -191,7 +195,11 @@ def _render_error_exit(e: CwcliError, project_name: str, *, verbose: bool = Fals
     stderr_console.print(f"[bold red]Error:[/bold red] {e.message}")
     if e.code == "ports.in_use":
         stderr_console.print(
-            "\n[yellow]Tip:[/yellow] Use the [cyan]--port[/cyan] flag to select "
+            "\n[yellow]Tip:[/yellow] If an instance using these ports was just removed, "
+            "they may still be releasing - wait a few seconds and retry."
+        )
+        stderr_console.print(
+            "[yellow]Tip:[/yellow] Otherwise, use the [cyan]--port[/cyan] flag to select "
             "a different starting port."
         )
         stderr_console.print(f"[dim]Example: cwcli init {project_name} --port 10000[/dim]")
@@ -376,10 +384,11 @@ def _start_services(project: str, bench_path: str) -> tuple[bool, bool | None]:
         )
         return False, None
     # core.start now blocks until the web server binds this bench's assigned port, so "running" is
-    # honest by the time we return. If it timed out, surface the warning so the
-    # user isn't told the web is up when it hasn't begun serving yet.
+    # honest by the time we return. If it timed out, or the port never got published
+    # to the host at all, surface the warning so the user isn't told the web is up
+    # when it isn't reachable.
     for warning in result.warnings:
-        if warning.code == "start.web_not_ready":
+        if warning.code in ("start.web_not_ready", "start.no_host_port"):
             stderr_console.print(f"[yellow]Warning:[/yellow] {warning.text}")
     running = result.status is not Status.NEEDS_CHOICE
     web_ready = result.data.web_ready if running and result.data is not None else None

{caffeinated_whale_cli-2.3.0 → caffeinated_whale_cli-2.3.1}/src/caffeinated_whale_cli/commands/start.py

@@ -322,7 +322,12 @@ def _start_project(
     # be visible here too, since restart's whole-stack path and the auto-start
     # path (ensure_containers_running) both funnel through this helper.
     for warning in result.warnings:
-        if warning.code in ("start.uid_align_failed", "bench.default_used", "start.web_not_ready"):
+        if warning.code in (
+            "start.uid_align_failed",
+            "bench.default_used",
+            "start.web_not_ready",
+            "start.no_host_port",
+        ):
             stderr_console.print(f"[yellow]Warning: {warning.text}[/yellow]")
         elif verbose:
             stderr_console.print(f"[dim]{warning.text}[/dim]")
@@ -522,7 +527,12 @@ def _run_start(
     # init.uid_align_failed precedent for the uid remap failure): both signal the
     # bench workspace may not behave as expected, not just verbose diagnostics.
     for warning in result.warnings:
-        if warning.code in ("start.uid_align_failed", "bench.default_used", "start.web_not_ready"):
+        if warning.code in (
+            "start.uid_align_failed",
+            "bench.default_used",
+            "start.web_not_ready",
+            "start.no_host_port",
+        ):
             stderr_console.print(f"[yellow]Warning: {warning.text}[/yellow]")
         elif verbose:
             stderr_console.print(f"[dim]{warning.text}[/dim]")

{caffeinated_whale_cli-2.3.0 → caffeinated_whale_cli-2.3.1}/src/caffeinated_whale_cli/core/init.py

@@ -472,6 +472,43 @@ def _project_containers_running(project_name: str) -> bool:
 
 _EXPECTED_COMPOSE_SERVICES = frozenset({"frappe", "mariadb", "redis-cache", "redis-queue"})
 
+# A just-removed instance's own port bindings can take a moment to fully
+# release (Docker's docker-proxy teardown lag, observed in the field to clear
+# within seconds), so a rapid remove-then-reinit (a CI purge-and-recreate
+# pattern) can see those SAME ports as still "in use" right after the old
+# instance is gone. 5 attempts a second apart absorbs that ordinary teardown
+# window before concluding the conflict is real and persistent.
+_PORT_CHECK_ATTEMPTS = 5
+_PORT_CHECK_RETRY_DELAY = 1.0
+
+
+def _ports_still_in_use(ports: list[int], *, emit: OnEvent) -> list[int]:
+    """Check host ports, retrying briefly before giving up.
+
+    Never silently treats a conflict as "no conflict" - it only delays the
+    verdict to absorb a transient teardown window. A port still in use after
+    every attempt is reported exactly as before: loudly, deterministically,
+    regardless of interactivity.
+    """
+    ports_in_use: list[int] = []
+    for attempt in range(_PORT_CHECK_ATTEMPTS):
+        port_status = check_ports_in_use(ports)
+        ports_in_use = [p for p, in_use in port_status.items() if in_use]
+        if not ports_in_use:
+            return []
+        if attempt < _PORT_CHECK_ATTEMPTS - 1:
+            emit(
+                InitNotice(
+                    code="ports.retry",
+                    text=(
+                        f"Port(s) {format_port_list(ports_in_use)} still in use "
+                        "(may be a just-removed instance releasing them); retrying..."
+                    ),
+                )
+            )
+            time.sleep(_PORT_CHECK_RETRY_DELAY)
+    return ports_in_use
+
 
 def _running_compose_services(project_name: str) -> set[str]:
     """Return this project's running compose service names."""
@@ -532,14 +569,17 @@ def init_instance(
     if not auto_start and not _project_containers_running(project_name):
         web_ports = list(range(port, port + 6))
         socketio_ports = list(range(port + 1000, port + 1006))
-        port_status = check_ports_in_use(web_ports + socketio_ports)
-        ports_in_use = [p for p, in_use in port_status.items() if in_use]
+        ports_in_use = _ports_still_in_use(web_ports + socketio_ports, emit=emit)
         if ports_in_use:
             raise CwcliError(
                 ErrorKind.CONFLICT,
                 "ports.in_use",
                 f"The following ports are already in use: {format_port_list(ports_in_use)}",
-                hint="Use the --port flag to select a different starting port.",
+                hint=(
+                    "If an instance using these ports was just removed, they may still be "
+                    "releasing - wait a few seconds and retry. Otherwise, use --port to "
+                    "select a different starting port."
+                ),
             )
 
     emit(InitStepStart(phase="project_dir", message="Creating project directory"))
@@ -581,11 +621,11 @@ def init_instance(
         )
     )
     content = compose_path.read_text()
-    content = content.replace("8000-8005:8000-8005", f"{port}-{port+5}:8000-8005")
+    web_mapping = f"{port}-{port + 5}:8000-8005"
+    content = content.replace("8000-8005:8000-8005", web_mapping)
     socketio_start = port + 1000
-    content = content.replace(
-        "9000-9005:9000-9005", f"{socketio_start}-{socketio_start+5}:9000-9005"
-    )
+    socketio_mapping = f"{socketio_start}-{socketio_start + 5}:9000-9005"
+    content = content.replace("9000-9005:9000-9005", socketio_mapping)
     # The upstream devcontainer template sets `working_dir: /workspace/development`
     # - a path cwcli never creates (its bench lives at /workspace/frappe-bench).
     # /workspace is a bind mount to CWCLI_HOME/projects/<name>/, so on `compose up`
@@ -617,6 +657,26 @@ def init_instance(
         (project_dir / "data").mkdir(parents=True, exist_ok=True)
         content = content.replace("- ..:/workspace:cached", f"- ../data:{bench_parent_path}:cached")
         content = content.replace("working_dir: /workspace", f"working_dir: {bench_parent_path}")
+        # frappe_docker removed the devcontainer template's ports block in favor
+        # of editor-managed forwarding. cwcli runs the compose project directly,
+        # so it must add the host publications when the downloaded template omits
+        # both mappings. Without them Docker starts a healthy but host-unreachable
+        # instance and every later string replacement remains a silent no-op.
+        if web_mapping not in content and socketio_mapping not in content:
+            working_dir = f"    working_dir: {bench_parent_path}"
+            published_ports = (
+                f'{working_dir}\n    ports:\n      - "{web_mapping}"\n      - "{socketio_mapping}"'
+            )
+            content = content.replace(working_dir, published_ports, 1)
+        if web_mapping not in content or socketio_mapping not in content:
+            compose_path.unlink()
+            raise CwcliError(
+                ErrorKind.PRECONDITION,
+                "compose.ports_missing",
+                "The downloaded Docker Compose template could not be configured "
+                "with the required host port mappings.",
+                hint="Retry init. If the error persists, report the upstream compose change.",
+            )
     compose_path.write_text(content)
 
     compose_base = ["docker", "compose", "-p", project_name, "-f", "docker-compose.yml"]

{caffeinated_whale_cli-2.3.0 → caffeinated_whale_cli-2.3.1}/src/caffeinated_whale_cli/core/scale.py

@@ -73,16 +73,17 @@ _WEB_CONTAINER_BASE = 8000
 _SOCKETIO_CONTAINER_BASE = 9000
 
 # The published ``ports:`` lines cwcli writes at init look like
-# ``- 16000-16005:8000-8005`` (web) and ``- 17000-17005:9000-9005`` (socketio).
+# ``- 16000-16005:8000-8005`` (web) and ``- 17000-17005:9000-9005`` (socketio),
+# optionally quoted as YAML strings.
 # Capture the host low bound and the container high bound so we know the current
 # published count and the host base to preserve when widening.
 _WEB_PORTS_RE = re.compile(
-    rf"(?m)^(?P<prefix>\s*-\s*)(?P<host_lo>\d+)-(?P<host_hi>\d+):"
-    rf"{_WEB_CONTAINER_BASE}-(?P<cont_hi>\d+)\s*$"
+    rf"(?m)^(?P<prefix>\s*-\s*)(?P<quote>['\"]?)(?P<host_lo>\d+)-(?P<host_hi>\d+):"
+    rf"{_WEB_CONTAINER_BASE}-(?P<cont_hi>\d+)(?P=quote)\s*$"
 )
 _SOCKETIO_PORTS_RE = re.compile(
-    rf"(?m)^(?P<prefix>\s*-\s*)(?P<host_lo>\d+)-(?P<host_hi>\d+):"
-    rf"{_SOCKETIO_CONTAINER_BASE}-(?P<cont_hi>\d+)\s*$"
+    rf"(?m)^(?P<prefix>\s*-\s*)(?P<quote>['\"]?)(?P<host_lo>\d+)-(?P<host_hi>\d+):"
+    rf"{_SOCKETIO_CONTAINER_BASE}-(?P<cont_hi>\d+)(?P=quote)\s*$"
 )
 
 
@@ -218,15 +219,17 @@ def _widen_ports_block(compose_text: str, published: _PublishedRange, count: int
     sio_hi_cont = _SOCKETIO_CONTAINER_BASE + count - 1
 
     def web_repl(match: re.Match) -> str:
+        quote = match.group("quote")
         return (
-            f"{match.group('prefix')}{published.web_base}-{web_hi_host}:"
-            f"{_WEB_CONTAINER_BASE}-{web_hi_cont}"
+            f"{match.group('prefix')}{quote}{published.web_base}-{web_hi_host}:"
+            f"{_WEB_CONTAINER_BASE}-{web_hi_cont}{quote}"
         )
 
     def sio_repl(match: re.Match) -> str:
+        quote = match.group("quote")
         return (
-            f"{match.group('prefix')}{published.socketio_base}-{sio_hi_host}:"
-            f"{_SOCKETIO_CONTAINER_BASE}-{sio_hi_cont}"
+            f"{match.group('prefix')}{quote}{published.socketio_base}-{sio_hi_host}:"
+            f"{_SOCKETIO_CONTAINER_BASE}-{sio_hi_cont}{quote}"
         )
 
     compose_text = _WEB_PORTS_RE.sub(web_repl, compose_text, count=1)

{caffeinated_whale_cli-2.3.0 → caffeinated_whale_cli-2.3.1}/src/caffeinated_whale_cli/core/start.py

@@ -107,6 +107,7 @@ def start(
     for container in containers:
         if container.status != "running":
             container.start()
+            container.reload()
 
     frappe_container = next(
         (c for c in containers if c.labels.get("com.docker.compose.service") == "frappe"),
@@ -159,6 +160,18 @@ def start(
     snapshot = supervision.discover_stack(frappe_container, resolved_path)
     if snapshot.supervisor_up:
         if not restart:
+            idle_processes = _launched_processes(frappe_container, resolved_path, snapshot)
+            idle_warnings = list(warnings)
+            if "web" in {p.label for p in idle_processes}:
+                idle_ports = resolvers.resolve_assigned_ports(
+                    frappe_container, [resolved_path], fill_defaults=False
+                ).get(resolved_path)
+                if idle_ports is not None:
+                    port_warning = _no_host_port_warning(
+                        frappe_container, project_name, resolved_path, idle_ports
+                    )
+                    if port_warning is not None:
+                        idle_warnings.append(port_warning)
             return Result(
                 status=Status.OK,
                 data=StartOutcome(
@@ -168,9 +181,9 @@ def start(
                     supervisor=supervision.SUPERVISOR,
                     log_path=log_path,
                     already_running=True,
-                    processes=_launched_processes(frappe_container, resolved_path, snapshot),
+                    processes=idle_processes,
                 ),
-                warnings=warnings,
+                warnings=idle_warnings,
             )
         supervision.stop_supervisor(frappe_container, resolved_path)
 
@@ -218,6 +231,11 @@ def start(
                         f"on :{ports[0]} in time. Check 'cwcli status' / 'cwcli logs'.",
                     )
                 )
+            port_warning = _no_host_port_warning(
+                frappe_container, project_name, resolved_path, ports
+            )
+            if port_warning is not None:
+                warnings.append(port_warning)
 
     return Result(
         status=Status.OK,
@@ -235,6 +253,29 @@ def start(
     )
 
 
+def _no_host_port_warning(
+    frappe_container, project_name: str, resolved_path: str, ports: tuple[int, int]
+) -> Message | None:
+    """An unmissable warning when this bench's web server has no live HOST
+    publish - "running" must stop meaning "reachable". A bench whose container
+    was created (or recreated) without its port mapping otherwise reports
+    fully healthy here and is only ever discovered by a caller's HTTP request
+    failing. Silent when a host port IS published; ``ports`` is the bench's
+    OWN container port, already resolved by the caller.
+    """
+    if (
+        resolvers.resolve_host_web_url(frappe_container, resolved_path, assigned_ports=ports)
+        is not None
+    ):
+        return None
+    return Message(
+        "start.no_host_port",
+        f"'{project_name}' is running, but no host port is published for this bench's "
+        f"web server (container port {ports[0]}) - it is not reachable from outside the "
+        "container. Recreate the instance with 'cwcli init' to publish its ports.",
+    )
+
+
 def _launched_processes(frappe_container, bench_path, snapshot) -> list[ProcessLaunch]:
     """The launched set: every expected Procfile label, with its PID if already up.
 

caffeinated_whale_cli-2.3.0/src/caffeinated_whale_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "2.3.0"