terp-cli 0.31.0__tar.gz → 0.32.0__tar.gz

{terp_cli-0.31.0 → terp_cli-0.32.0}/PKG-INFO

@@ -1,19 +1,19 @@
 Metadata-Version: 2.5
 Name: terp-cli
-Version: 0.31.0
+Version: 0.32.0
 Summary: Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs.
 Project-URL: Repository, https://github.com/AITT-NL/terp-framework
 Project-URL: Changelog, https://github.com/AITT-NL/terp-framework/blob/main/CHANGELOG.md
 License-Expression: Apache-2.0
 Requires-Python: >=3.13
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: terp-arch==0.31.0
-Requires-Dist: terp-core==0.31.0
-Requires-Dist: terp-migrations==0.31.0
+Requires-Dist: terp-arch==0.32.0
+Requires-Dist: terp-core==0.32.0
+Requires-Dist: terp-migrations==0.32.0
 Provides-Extra: jobs
-Requires-Dist: terp-cap-outbox==0.31.0; extra == 'jobs'
-Requires-Dist: terp-cap-scheduler-apscheduler==0.31.0; extra == 'jobs'
+Requires-Dist: terp-cap-outbox==0.32.0; extra == 'jobs'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.32.0; extra == 'jobs'
 Provides-Extra: scheduler
-Requires-Dist: terp-cap-scheduler-apscheduler==0.31.0; extra == 'scheduler'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.32.0; extra == 'scheduler'
 Provides-Extra: worker
-Requires-Dist: terp-cap-outbox==0.31.0; extra == 'worker'
+Requires-Dist: terp-cap-outbox==0.32.0; extra == 'worker'

{terp_cli-0.31.0 → terp_cli-0.32.0}/pyproject.toml

@@ -4,18 +4,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "terp-cli"
-version = "0.31.0"
+version = "0.32.0"
 description = "Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs."
 requires-python = ">=3.13"
 license = "Apache-2.0"
 dependencies = [
-    "terp-core==0.31.0",
+    "terp-core==0.32.0",
     # `terp migrate` delegates to terp-migrations (lazily imported), keeping Alembic
     # off the path for `terp inspect` / `terp guide` while making migrations work.
-    "terp-migrations==0.31.0",
+    "terp-migrations==0.32.0",
     # `terp guide rules` projects the live rule registry; terp-arch is imported lazily
     # (only when that topic is rendered), so it stays off the common `terp guide` path.
-    "terp-arch==0.31.0",
+    "terp-arch==0.32.0",
     # `terp verify --only env-seams` and `terp smoke` read the compose profiles as data
     # (anchors and `<<:` merge keys resolved), so both answer without a Docker daemon or
     # even the `docker` binary. Declared explicitly rather than leant on: every app
@@ -29,11 +29,11 @@ dependencies = [
 # or a scheduler engine into apps that only use inspect/check/migrate. Deployments can select
 # one process role, while `jobs` is the convenient complete jobs-process bundle.
 [project.optional-dependencies]
-worker = ["terp-cap-outbox==0.31.0"]
-scheduler = ["terp-cap-scheduler-apscheduler==0.31.0"]
+worker = ["terp-cap-outbox==0.32.0"]
+scheduler = ["terp-cap-scheduler-apscheduler==0.32.0"]
 jobs = [
-    "terp-cap-outbox==0.31.0",
-    "terp-cap-scheduler-apscheduler==0.31.0",
+    "terp-cap-outbox==0.32.0",
+    "terp-cap-scheduler-apscheduler==0.32.0",
 ]
 
 [project.scripts]

{terp_cli-0.31.0 → terp_cli-0.32.0}/src/terp/cli/docker.py

@@ -29,6 +29,8 @@ import subprocess
 from collections.abc import Callable, Sequence
 
 from terp.cli import ports
+from terp.cli._output import emit
+from terp.cli.docker_masks import clear_stale_masks
 
 _DEFAULT_COMPOSE = "docker-compose.yml"
 
@@ -229,6 +231,18 @@ def run_docker_dev_command(
     _, note = ports.ensure_assigned(path.parent)
     if note:
         print(note)
+    # Before `watch` creates anything: a workbench from before 0.30.0 holds its
+    # node_modules mask as a volume, which Compose would reattach over the tmpfs the
+    # compose file now declares and keep serving old packages from
+    # (terp.cli.docker_masks). No docker on PATH is `watch`'s to report, in its own
+    # words, not this check's.
+    try:
+        cleared = clear_stale_masks(path, project_name=project_name, capture=capture or _capture)
+    except OSError:
+        cleared = ""
+    if cleared:
+        # Through the CLI's one output seam, and flushed: `watch` holds the terminal next.
+        emit(cleared)
     status = (runner or _run)(docker_dev_argv(path, project_name=project_name))
     message = f"docker compose watch exited with status {status}"
     if status == 0:

terp_cli-0.32.0/src/terp/cli/docker_masks.py

@@ -0,0 +1,167 @@
+"""A mask the compose file declares as ``tmpfs`` that a running workbench still holds as a volume.
+
+0.30.0 turned the frontend's ``node_modules`` mask from an anonymous volume into a
+``tmpfs``, so that a dependency bump reaches the running dev server. A workbench that
+was already up before the upgrade does not get it. When Compose recreates a container
+it reattaches the old container's anonymous volumes by target path, and that wins over
+the ``tmpfs`` now declared at the same path. The dev server then keeps serving the
+first boot's packages from that volume, with every container healthy and the page
+answering 200. An upgraded-on-paper workbench and an upgraded one look identical.
+
+Compose owns that reattachment, so the place to undo it is before ``watch`` creates
+anything. For every service whose mount at a ``tmpfs`` path is still a volume, the
+container is removed, and so is that volume and only that one. Compose then creates
+both fresh, with the ``tmpfs``. The volume held nothing but a copy of the image's
+packages: the mask exists to hide the checkout's ``node_modules``, never to keep one.
+A named volume is never touched, and neither is any other volume of the container.
+
+Best effort, like the failure diagnosis next door: a daemon that is not up, a compose
+file Compose cannot read, or a ``ps`` with no containers yet means there is nothing to
+undo, and ``watch`` speaks for itself.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from collections.abc import Callable, Sequence
+
+#: Runs argv, returning ``(exit status, combined output)``.
+Capture = Callable[[Sequence[str]], tuple[int, str]]
+
+
+def _compose(compose_file: pathlib.Path, project_name: str | None) -> list[str]:
+    argv = ["docker", "compose", "-f", str(compose_file)]
+    if project_name:
+        argv += ["-p", project_name]
+    return argv
+
+
+def _json_entries(output: str) -> list[dict]:
+    """A JSON array, one object, or newline-delimited objects, as Compose has printed each."""
+    stripped = output.strip()
+    if not stripped:
+        return []
+    try:
+        parsed = json.loads(stripped)
+    except json.JSONDecodeError:
+        entries = []
+        for line in stripped.splitlines():
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        return [entry for entry in entries if isinstance(entry, dict)]
+    items = parsed if isinstance(parsed, list) else [parsed]
+    return [entry for entry in items if isinstance(entry, dict)]
+
+
+def tmpfs_targets(config_output: str) -> dict[str, frozenset[str]]:
+    """Per service, the paths ``docker compose config --format json`` declares as ``tmpfs``.
+
+    Both spellings count: a ``volumes`` entry of ``type: tmpfs``, and the service-level
+    ``tmpfs:`` list (whose entries may carry ``:options`` after the path).
+    """
+    try:
+        config = json.loads(config_output)
+    except json.JSONDecodeError:
+        return {}
+    services = config.get("services") if isinstance(config, dict) else None
+    if not isinstance(services, dict):
+        return {}
+    found: dict[str, frozenset[str]] = {}
+    for name, service in services.items():
+        if not isinstance(service, dict):
+            continue
+        targets = {
+            volume["target"]
+            for volume in service.get("volumes") or ()
+            if isinstance(volume, dict)
+            and volume.get("type") == "tmpfs"
+            and isinstance(volume.get("target"), str)
+        }
+        listed = service.get("tmpfs") or ()
+        for entry in [listed] if isinstance(listed, str) else listed:
+            if isinstance(entry, str) and entry:
+                targets.add(entry.split(":", 1)[0])
+        if targets:
+            found[name] = frozenset(targets)
+    return found
+
+
+def containers(ps_output: str) -> dict[str, str]:
+    """Service name to container id, from ``docker compose ps --all --format json``."""
+    found: dict[str, str] = {}
+    for entry in _json_entries(ps_output):
+        service, container = entry.get("Service"), entry.get("ID")
+        if isinstance(service, str) and isinstance(container, str) and container:
+            found.setdefault(service, container)
+    return found
+
+
+def stale_volumes(inspect_output: str, targets: frozenset[str]) -> tuple[str, ...]:
+    """The volumes ``docker inspect`` shows mounted at a path that should be a ``tmpfs``.
+
+    Only a volume counts, never a bind: a bind at that path is somebody's deliberate
+    choice, and removing it is not this command's to decide.
+    """
+    names: list[str] = []
+    for container in _json_entries(inspect_output):
+        for mount in container.get("Mounts") or ():
+            if (
+                isinstance(mount, dict)
+                and mount.get("Type") == "volume"
+                and mount.get("Destination") in targets
+                and isinstance(mount.get("Name"), str)
+                and mount["Name"] not in names
+            ):
+                names.append(mount["Name"])
+    return tuple(names)
+
+
+def clear_stale_masks(
+    compose_file: pathlib.Path,
+    *,
+    project_name: str | None = None,
+    capture: Capture,
+) -> str:
+    """Undo a pre-0.30.0 ``node_modules`` volume before ``watch``; what was done, or ``""``."""
+    compose = _compose(compose_file, project_name)
+    status, config = capture([*compose, "config", "--format", "json"])
+    targets = tmpfs_targets(config) if status == 0 else {}
+    if not targets:
+        return ""
+    status, ps_output = capture([*compose, "ps", "--all", "--format", "json"])
+    running = containers(ps_output) if status == 0 else {}
+    stale: dict[str, tuple[str, ...]] = {}
+    for service, paths in sorted(targets.items()):
+        container = running.get(service)
+        if container is None:
+            continue
+        status, inspected = capture(["docker", "inspect", container])
+        volumes = stale_volumes(inspected, paths) if status == 0 else ()
+        if volumes:
+            stale[service] = volumes
+    if not stale:
+        return ""
+    services = sorted(stale)
+    volumes = [volume for service in services for volume in stale[service]]
+    listing = ", ".join(repr(service) for service in services)
+    removed, _ = capture([*compose, "rm", "--stop", "--force", *services])
+    if removed == 0:
+        removed, _ = capture(["docker", "volume", "rm", *volumes])
+    if removed != 0:
+        renew = [*compose, "up", "-d", "--no-deps", "--force-recreate", "--renew-anon-volumes"]
+        return (
+            f"terp docker dev: {listing} still mount(s) a volume where the compose file "
+            "declares a tmpfs (a workbench from before 0.30.0), so the dev server would keep "
+            "serving its old packages. Removing it failed; once, by hand:\n"
+            f"  {' '.join([*renew, *services])}\n"
+            f"  docker volume rm {' '.join(volumes)}"
+        )
+    return (
+        f"terp docker dev: {listing} still mounted a volume where the compose file declares "
+        "a tmpfs (a workbench from before 0.30.0), so the dev server kept serving the packages "
+        "it first booted with. Removed the container and that volume; this start creates both "
+        "fresh."
+    )

{terp_cli-0.31.0 → terp_cli-0.32.0}/src/terp/cli/verify.py

@@ -1043,6 +1043,24 @@ def _node_modules_problem(root: pathlib.Path, workspace: str) -> str | None:
     except (OSError, ValueError):
         return None
 
+    # A directory with none of the lockfile's platform-neutral packages in it is not
+    # a tree for another platform but no tree at all -- an install that never ran,
+    # or a fresh mount point. Calling it "a different platform" sends the reader
+    # looking for a second machine that does not exist. Neutral ones only: every
+    # platform installs those, so not one of them present means nothing was.
+    neutral = [
+        name
+        for name, entry in packages.items()
+        if name.startswith("node_modules/")
+        and isinstance(entry, dict)
+        and not (entry.get("os") or entry.get("cpu") or entry.get("libc"))
+    ]
+    if neutral and not any((directory / name).exists() for name in neutral):
+        return (
+            f"{label} is missing (the directory is there, but holds none of the "
+            f"lockfile's packages) — {subject} cannot run.\n  Fix: {fix}"
+        )
+
     system, arch = _node_platform()
     libc = _node_libc(system)
     missing = [

{terp_cli-0.31.0 → terp_cli-0.32.0}/src/terp/cli/version.py

@@ -236,6 +236,7 @@ _APP_OWNED_SCAFFOLD_FILES = (
     "control_plane/app_operations.py",
     "environment.schema.json",
     "escape-hatch-budget.json",
+    "frontend/escape-hatch-budget.json",
     "frontend/layout-contract.json",
     "frontend/src/house-style.css",
     "frontend/src/routes.gen.d.ts",
@@ -450,8 +451,11 @@ def _rerender_recipe(target: str, current: str, count: int) -> list[str]:
         "     and its own diff is much easier to review on its own.",
         "  3. copier update          (or the Studio's upgrade flow, which records the",
         "     answers file it needs). This rewrites EVERY file the template owns and",
-        "     writes the terp-* and @terpjs/* pins for you.",
-        "  4. Resolve what it reports. Two conflicts are structural rather than bad luck,",
+        "     writes the terp-* and @terpjs/* pins for you. Its --pretend lists none of",
+        "     that, so do not judge the update by a dry run: review what it did as its",
+        "     own diff (git status, git diff) — that is why step 2 cleans the tree.",
+        "  4. Resolve what it reports: conflict markers in the file, or a *.rej beside it",
+        "     when it ran with --conflict rej. Two conflicts are structural, not bad luck,",
         "     because the template owns the file and your app also writes to it:",
         "       pyproject.toml            keep your dependencies, take the terp-* pins.",
         "       control_plane/operations.py  the capability folding is the template's;",
@@ -468,7 +472,10 @@ def _rerender_recipe(target: str, current: str, count: int) -> list[str]:
         "  in while the source is bind-mounted, so correct new code reloads against old",
         "  libraries and dies on an import nowhere near its cause. `terp docker dev`",
         "  rebuilds on a pyproject.toml change; a plain `docker compose up` does not,",
-        "  and `terp verify` now refuses the skew either way.",
+        "  and `terp verify` now refuses the skew either way. Coming from 0.29 or older,",
+        "  a stack that is already up keeps its old node_modules volume where 0.30.0",
+        "  declares a tmpfs. `terp docker dev` removes it before it starts; with plain",
+        "  compose, run `up --force-recreate --renew-anon-volumes` once.",
         "",
         "A green gate proves the upgrade did not break this app. It cannot prove the",
         "release did not change something this app should adopt — step 1 is the only",