workmap 0.1.0__py3-none-any.whl

workmap/config.py

@@ -0,0 +1,589 @@
+"""Where workmap keeps its settings, what counts as a project, and which
+colour each one gets.
+
+Project identity lives here rather than in model.py because it is a question
+about a disk and a setting, not about a process: which directories the user
+calls project directories, which of the things inside them are projects, and
+what a name has to be for `work` to be able to take it. model.py answers the
+other half, what a *process* is, and having the two in one file is what let
+"the first path component under a root" spread into three functions that
+disagreed. See ProjectIndex."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+
+from .themes import ASSIGN_ORDER, PROFILE_SWATCHES
+
+CONFIG_DIR = Path.home() / ".config" / "workmap"
+CONFIG_PATH = CONFIG_DIR / "projects.json"
+SESSION_VISIBLE = 3
+
+# Below this, an orphaned tree is not worth a line on screen.
+#
+# The number only means something alongside how memory is measured. It was 8,
+# chosen against `ps` RSS, where it sat *above* most real orphans: eleven
+# orphaned astro servers holding 1.6 GB reported 1-2 MB of RSS each and were
+# silently filtered out. The tool was blind to exactly the leak it exists to
+# find. Against phys_footprint the smallest genuine dev server on a real
+# machine is about 10 MB (a bare esbuild service), so this is set below that
+# on purpose. It excludes processes that are already effectively gone and
+# nothing else.
+#
+# Erring low is the right direction: an orphan is worth quitting because it
+# holds a port and a file watcher, not only because it holds memory.
+ORPHAN_FLOOR_MB = 4
+# The smallest real dev-server footprint observed, which the floor must stay
+# under. Tested, so raising the floor past it fails loudly.
+SMALLEST_REAL_DEV_SERVER_MB = 10
+
+# Directories that commonly hold a developer's projects, tried in order when
+# nothing has been configured. Only used to guess; `roots` in the config file
+# is what actually decides.
+ROOT_GUESSES = ("dev", "code", "src", "projects", "work", "Developer")
+
+
+def load_config() -> dict:
+    """The settings, or the empty default. Reading must never raise.
+
+    It used to make the directory first, and that call sat outside the try.
+    ROOTS is computed at import, so on a machine where ~/.config cannot hold a
+    directory (it exists as a file, the home is read-only) importing workmap
+    at all ended in a traceback: `workmap --help`, `workmap --version` and
+    `import workmap` in someone else's program all died before reaching the
+    line that would have explained anything.
+
+    Making the directory belongs to writing, which is where it now happens.
+    """
+    try:
+        return json.loads(CONFIG_PATH.read_text())
+    except Exception:
+        return {"profiles": {}}
+
+
+# Where an unreadable settings file is kept rather than thrown away.
+KEPT_SUFFIX = ".unreadable"
+
+
+def kept_path() -> Path:
+    return CONFIG_PATH.with_name(CONFIG_PATH.name + KEPT_SUFFIX)
+
+
+def _keep_anything_unreadable() -> None:
+    """Move a settings file we cannot parse aside instead of over-writing it.
+
+    load_config() turns any parse failure into an empty default and says
+    nothing, and every write path here is a read-modify-write built on it. So
+    one stray comma in projects.json cost the user their roots, their agents
+    and every colour they had chosen, permanently and silently, at the next
+    thing that happened to write: `workmap paint`, `workmap agent`, or the
+    `work` function, which writes twice per invocation.
+
+    Failing to parse is not the same as having nothing to say. Keep it.
+    """
+    if not CONFIG_PATH.exists():
+        return
+    try:
+        json.loads(CONFIG_PATH.read_text())
+        return
+    except (OSError, ValueError):
+        pass
+    try:
+        os.replace(CONFIG_PATH, kept_path())
+    except OSError:
+        pass
+
+
+def save_config(cfg: dict) -> None:
+    """Write the settings file in one step, keeping anything unreadable.
+
+    write_text() truncates and then writes, so the file is empty for the gap
+    between the two and a crash in it leaves nothing. A reader that catches
+    that moment sees no settings and, being a read-modify-write itself, makes
+    it permanent. Writing beside it and renaming is atomic: a reader gets the
+    old file or the new one, never half of either.
+    """
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    _keep_anything_unreadable()
+    tmp = CONFIG_PATH.with_name(CONFIG_PATH.name + ".tmp")
+    tmp.write_text(json.dumps(cfg, indent=2) + "\n")
+    os.replace(tmp, CONFIG_PATH)
+
+
+def detect_roots() -> list[Path]:
+    home = Path.home()
+    return [home / name for name in ROOT_GUESSES if (home / name).is_dir()]
+
+
+def configured_roots() -> list[Path]:
+    """Where projects live, in order of precedence.
+
+    A project is the first directory *under* a root, so the root has to be the
+    directory that contains your projects, not its parent. Pointing at ~/dev
+    when your work is in ~/dev/Company would name every project "Company".
+    That's why this is configuration and not a guess baked into the source.
+    """
+    env = os.environ.get("WORKMAP_ROOTS") or os.environ.get("DEVSTACK_ROOTS", "")
+    if env:
+        return [Path(p).expanduser() for p in env.split(":") if p]
+    configured = load_config().get("roots") or []
+    if configured:
+        return [Path(p).expanduser() for p in configured]
+    return detect_roots()
+
+
+ROOTS = configured_roots()
+
+NO_ROOTS_ADVICE = (
+    "workmap doesn't know where you keep your projects yet. Run: workmap setup"
+)
+
+
+def roots_advice() -> str:
+    """What to tell the user when nothing can be a project.
+
+    Without roots the scanner cannot say which directories are projects, so it
+    declines to call anything an orphan rather than treating every directory
+    on the machine as one. That is the safe answer but a silent one: a fresh
+    install would just never find anything and never explain why.
+
+    A root that is set but is not there is the same silence with a harder
+    cause to guess: a typo in the config file, a disk that is not mounted, a
+    directory that has been renamed. project_dirs() steps over an unreadable
+    root without a word, so `workmap projects` printed nothing and `workmap`
+    drew an empty desk, both of which look exactly like having no work open.
+
+    Asked as "can it be listed", not "is it a directory". Those are different
+    questions and only the first is the one the tool depends on: a folder
+    whose permissions nobody may read answers is_dir() with True and iterdir()
+    with an error, so it was reported as fine while every project in it and
+    every orphan under it silently vanished.
+    """
+    if not ROOTS:
+        return NO_ROOTS_ADVICE
+    missing = [str(r) for r in ROOTS if not _can_be_listed(r)]
+    if not missing:
+        return ""
+    named = ", ".join(missing)
+    if len(missing) == len(ROOTS):
+        return (f"workmap can't read where you keep your projects: {named}. "
+                f"Run: workmap setup")
+    return f"one of your project folders can't be read: {named}"
+
+
+def _can_be_listed(root: Path) -> bool:
+    try:
+        next(iter(root.iterdir()), None)
+        return True
+    except OSError:
+        return False
+
+
+def default_profile(name: str) -> str:
+    """The colour a project gets when the user has not chosen one.
+
+    Derived from the name rather than handed out in first-seen order, so it is
+    the same on every scan, every machine, and whatever else is open at the
+    time. The order-based version had to be written to disk to be stable,
+    which meant a scan, something that happens on every keypress, rewrote
+    the config file, and every synthetic bucket name the scanner produced
+    ("other", "home", and once an empty string) was saved as if it were a
+    project the user cared about.
+
+    Two projects can land on the same colour. That is a much smaller problem
+    than colours moving around between refreshes.
+    """
+    if not name:
+        return "Basic"
+    # A stable hash: Python's is randomised per process, which would defeat
+    # the entire point.
+    digest = hashlib.sha256(name.encode("utf-8")).digest()
+    return ASSIGN_ORDER[digest[0] % len(ASSIGN_ORDER)]
+
+
+def profile_for(name: str, cfg: dict) -> str:
+    """The colour to draw this project in. Reads only; never writes.
+
+    An explicit choice always wins; everything else is derived. This is what
+    the scanner calls, so scanning cannot touch the disk.
+    """
+    chosen = cfg.get("profiles", {}).get(name)
+    return chosen if chosen else default_profile(name)
+
+
+# Cc control, Cf format (bidi overrides, zero widths, the byte order mark),
+# Cs lone surrogate (what an undecodable filename arrives as, and what raises
+# on the way back out), Zl and Zp line and paragraph separator.
+_UNADDRESSABLE = frozenset({"Cc", "Cf", "Cs", "Zl", "Zp"})
+
+
+def addressable(name: str) -> bool:
+    """Can this directory name be used as a project name?
+
+    Everything a project name touches is line-oriented or goes straight to a
+    terminal. `workmap projects` prints one per line and the `work` function
+    picks by line number, so a name containing a newline is two entries in the
+    list and neither of them is a directory. A name containing an escape
+    character is worse than useless: it is printed unquoted into the picker and
+    into the tab title, where it can move the cursor and repaint the screen.
+
+    Refusing is better than rewriting. A sanitised name no longer matches the
+    directory it came from, so `work` would land somewhere else or nowhere;
+    a name that cannot be typed safely is one the tool should not offer.
+
+    "Newline" is not only `\\n`. `str.splitlines()` breaks on ten characters,
+    and the ASCII check this used to be admitted three of them: U+0085, U+2028
+    and U+2029. A name with one in it was one entry in `workmap projects` and
+    two lines on screen, which is the exact failure the rule was written for.
+
+    The rest of what is refused here is invisible or reverses what follows it.
+    A zero-width space makes two different projects show the same name, and a
+    right-to-left override makes a name read as something other than the
+    directory it opens. Both survive every sanitiser downstream, and a project
+    name is printed into a tab title and into the prompt that asks whether to
+    signal a list of processes, which is the last place to be showing somebody
+    text that does not say what it is.
+
+    Categories rather than a list of codepoints, because the list keeps
+    growing. Measured identical on Unicode 13 and 16, so the CI floor and the
+    newest interpreter agree: emoji and the wider spaces stay allowed, and an
+    unassigned codepoint stays allowed too, since which ones those are is the
+    one thing that does change between versions.
+    """
+    if not name:
+        return False
+    return all(unicodedata.category(ch) not in _UNADDRESSABLE for ch in name)
+
+
+def _resolved(path: Path) -> Path:
+    try:
+        return path.resolve()
+    except OSError:
+        return path
+
+
+@dataclass(frozen=True)
+class ProjectId:
+    """One project, under both the names it answers to.
+
+    A project is reached one way and reported another. `path` is how the user
+    got to it, `<root>/offsite`, which is where `work offsite` has to land.
+    `real` is what the kernel says, `/elsewhere/offsite`, because a process's
+    working directory comes back already resolved and there is no call that
+    returns the link it was reached through. Keeping both is the whole of what
+    it takes to support a project that is a symlink; keeping one was the whole
+    of why it did not work.
+    """
+    name: str
+    path: Path
+    real: Path
+
+
+class ProjectIndex:
+    """Which project a path belongs to. One question, one answer.
+
+    This used to be three: `scan.under_a_root()` asked whether a path was in a
+    project, `model.project_from_path()` asked which one, and
+    `config.project_dirs()` decided which directories were offered as
+    projects. All three answered by taking the first path component under a
+    configured root, and all three disagreed. Measured, with one root set:
+
+        <root>             under a root, and a project named after the root
+        <root>/.hidden     under a root, and a project named ".hidden"
+        <root>/nosuchdir   under a root, and a project named "nosuchdir"
+
+    while project_dirs() refused all three, so `workmap kill` could name
+    something `work` could not reach and `workmap projects` did not list. A
+    prefix rule invents projects, because a prefix is a shape and a project is
+    a directory.
+
+    So identity stops being derived and becomes a lookup. This is built once
+    per scan from the directories that are actually there, and a path belongs
+    to the project whose own path is the longest one above it. That single
+    rule replaces the two it came from: nested roots need no precedence order,
+    because the inner project's path is simply the longer match.
+
+    Nothing here touches the filesystem. build_project_index() does the
+    listing and hands the answers over, which is what lets everything that
+    reads it stay a total function of its arguments.
+    """
+
+    def __init__(self, projects, home: "Path | None" = None, unreadable=()):
+        self.projects = list(projects)
+        self.home = home
+        # Roots that are there but would not list. Carried so the desk can say
+        # so: without it, one unreadable root means every project under it and
+        # every orphan in them disappear, and the desk that results is
+        # indistinguishable from having nothing open. roots_advice() reports
+        # it, and it cannot be found by asking is_dir(), which a directory
+        # nobody may read still answers True.
+        self.unreadable = list(unreadable)
+        keyed: dict[Path, ProjectId] = {}
+        # Two projects can resolve to one directory: `<root>/api` and
+        # `<root>/api-link -> api`. The one reached directly wins, and then the
+        # shorter path, so which name an orphan there is filed under is a
+        # property of the disk rather than of the order a listing came back in.
+        for p in sorted(self.projects,
+                        key=lambda p: (p.path != p.real, len(str(p.path)))):
+            # Both spellings, so a working directory (always resolved) and a
+            # command line (whatever was typed) reach the same project without
+            # either reader having to resolve anything.
+            keyed.setdefault(p.real, p)
+            keyed.setdefault(p.path, p)
+        self._keys = sorted(keyed.items(),
+                            key=lambda kv: len(str(kv[0])), reverse=True)
+
+    def of_path(self, path: "Path | None") -> "ProjectId | None":
+        """The project this path is in, or None if it is in none.
+
+        None is the honest answer for a path under a root that is not a
+        project: the root itself, a dot directory, a directory that has been
+        deleted since. Every one of those used to become a project named after
+        a path component.
+        """
+        if path is None:
+            return None
+        for key, project in self._keys:
+            if path == key or key in path.parents:
+                return project
+        return None
+
+    def named(self, name: str) -> "ProjectId | None":
+        for project in self.projects:
+            if same_name(project.name, name):
+                return project
+        return None
+
+    def in_cmd(self, cmd: str) -> "ProjectId | None":
+        """The project a command line names, if it names one.
+
+        Only a fallback, for a process whose working directory cannot be read.
+        Where a process is running is a better answer than what is written in
+        its arguments, and scan.build_projects() asks in that order. Reading a
+        project out of an argument is the mistake this codebase keeps finding,
+        so this is the one rule allowed to look at the whole command line, and
+        it is bounded on the other side instead: it can only ever answer with
+        a project that is on the disk right now. It used to be able to invent
+        one out of any word that followed a root.
+
+        Longest path first, so `<root>/my project` wins over `<root>/my`, and
+        the character after the match has to end the name, so `<root>/myapp`
+        is not `<root>/my`.
+        """
+        for key, project in self._keys:
+            text = str(key)
+            start = 0
+            while True:
+                idx = cmd.find(text, start)
+                if idx < 0:
+                    break
+                after = cmd[idx + len(text): idx + len(text) + 1]
+                if after in ("", "/", " "):
+                    return project
+                start = idx + 1
+        return None
+
+    def bucket_for(self, path: "Path | None") -> "tuple[str, Path | None]":
+        """Where to file a Terminal window whose directory is not a project.
+
+        Windows are not orphans and belong on the desk wherever they are, so
+        they need somewhere to go when of_path() says None. Orphans do not get
+        this: a process with no project is not offered for killing, which is
+        the safe direction and the reason the two questions are separate.
+
+        Compared resolved on both sides. It once compared a resolved path
+        against a raw Path.home(), so on any machine whose home is reached
+        through a symlink the home bucket never matched and every directory
+        beside it became a project named after itself.
+        """
+        if path is None:
+            return "other", None
+        if self.home is not None and self.home in (path, path.parent):
+            return "home", self.home
+        return path.name, path
+
+
+def project_map() -> tuple[list[ProjectId], list[Path]]:
+    """Every project on disk, and every root that would not list.
+
+    build_projects() only knows about projects with live sessions, which is
+    the wrong list for starting work: the project you want next is usually the
+    one with nothing open. This is the one definition of what a project is,
+    and it is a directory rather than a path prefix.
+
+    Two projects may share a name. Nothing is dropped here, because dropping
+    is what the name-keyed version did: with two roots each holding an `api`,
+    only the first was kept, so every orphan under the second was invisible
+    for good. Which one `work api` lands in is a question about a typed name,
+    and it is answered in project_dirs(), where dropping one is the point.
+
+    Measured on this machine: 1.5ms for 44 projects, plus 0.5ms to resolve
+    them all, against a scan that costs about a second.
+    """
+    # A directory that is itself a configured root holds projects, it is not
+    # one. With ~/dev and ~/dev/Company both set, "Company" was offered as a
+    # project and `work Company` landed in the folder holding the real ones.
+    root_paths = {_resolved(r) for r in ROOTS}
+    home = _resolved(Path.home())
+    found: list[ProjectId] = []
+    unreadable: list[Path] = []
+    for root in ROOTS:
+        try:
+            entries = sorted(root.iterdir())
+        except OSError:
+            unreadable.append(root)
+            continue
+        for entry in entries:
+            if entry.name.startswith(".") or not addressable(entry.name):
+                continue
+            try:
+                if not entry.is_dir():
+                    continue
+            except OSError:
+                continue
+            real = _resolved(entry)
+            if real in root_paths or _holds_projects(real, root_paths, home):
+                continue
+            found.append(ProjectId(name=entry.name, path=entry, real=real))
+    return found, unreadable
+
+
+def _holds_projects(real: Path, root_paths: set, home: Path) -> bool:
+    """Is this directory somewhere projects live, rather than a project?
+
+    The same rule as "a root is not a project", followed through a link. A
+    symlink is allowed to leave its root, which is the whole point of
+    supporting one, so `<root>/offsite -> /Volumes/ext/offsite` is a project.
+    `<root>/dotfiles -> ~` is not, and neither is `<root>/current -> ..`: both
+    resolve to a directory holding the projects rather than to one of them.
+
+    Without this, following the link made every directory in the home folder
+    part of one project. A dev server in ~/scratch would be listed as an
+    orphan of "dotfiles" and `workmap kill dotfiles` would signal it, which is
+    a great deal more than anyone asked for by making a symlink.
+    """
+    if real == home or real in home.parents:
+        return True
+    return any(root == real or real in root.parents for root in root_paths)
+
+
+def build_project_index() -> ProjectIndex:
+    """The index, read off the disk. The one call here that does any listing."""
+    projects, unreadable = project_map()
+    return ProjectIndex(projects, home=_resolved(Path.home()),
+                        unreadable=unreadable)
+
+
+def project_dirs() -> list[tuple[str, Path]]:
+    """Every project, as (name, where to go). What `work` and `projects` read.
+
+    One entry per name, first root first, because this answers a typed name
+    and a typed name can only go one place.
+    """
+    seen: dict[str, Path] = {}
+    for project in project_map()[0]:
+        seen.setdefault(project.name, project.path)
+    return sorted(seen.items())
+
+
+def same_name(a: str, b: str) -> bool:
+    """Do these name the same project?
+
+    Compared with accents composed on both sides. macOS filesystems disagree
+    about whether "é" is one character or two: APFS keeps what you gave it,
+    HFS+ decomposes, and a name typed at a keyboard is composed. So a project
+    read off one volume did not match itself typed at a prompt, and the tool
+    answered `There's no project called "café-api". Did you mean: café-api?`
+    with the two spellings looking identical on screen.
+    """
+    return (unicodedata.normalize("NFC", a) == unicodedata.normalize("NFC", b))
+
+
+def project_path(name: str) -> Path | None:
+    """Where a project lives, by name. None if there is no such directory."""
+    for candidate, path in project_dirs():
+        if same_name(candidate, name):
+            return path
+    return None
+
+
+# The agents worth offering, and how to launch each one. A key is only shown
+# if its binary is actually on PATH, so nobody is offered a tool they do not
+# have. Override any of these under "agents" in the config file.
+AGENT_DEFAULTS = {
+    "claude": "claude",
+    "codex": "codex",
+    "cursor": "cursor-agent",
+    "aider": "aider",
+    "gemini": "gemini",
+    "opencode": "opencode",
+    "goose": "goose",
+    "amp": "amp",
+}
+
+
+def configured_agents(cfg: dict | None = None) -> dict:
+    """The defaults, with anything in the config layered on top.
+
+    Merging rather than replacing means installing workmap is enough to get
+    the agents you already have offered to you. To take one off the list,
+    set it to "" or null. Otherwise there would be no way to say no.
+    """
+    cfg = load_config() if cfg is None else cfg
+    agents = dict(AGENT_DEFAULTS)
+    agents.update(cfg.get("agents") or {})
+    return agents
+
+
+def available_agents(cfg: dict | None = None) -> dict:
+    """Configured agents whose command exists on this machine."""
+    out = {}
+    for key, command in configured_agents(cfg).items():
+        words = (command or "").split()
+        if words and shutil.which(words[0]):
+            out[key] = command
+    return out
+
+
+def default_agent(cfg: dict | None = None) -> str:
+    cfg = load_config() if cfg is None else cfg
+    chosen = cfg.get("default_agent")
+    available = available_agents(cfg)
+    if chosen in available or chosen == "none":
+        return chosen
+    return next(iter(available), "none")
+
+
+def set_default_agent(name: str) -> str:
+    cfg = load_config()
+    cfg["default_agent"] = name
+    save_config(cfg)
+    return name
+
+
+def remembered_profile(name: str, cfg: dict, available: set) -> str:
+    """profile_for(), but remember the answer, and only pick a real colour.
+
+    Only for paths where the user has expressed intent about this project:
+    painting it, organizing it, choosing its colour. Writing is the point
+    here, so unlike profile_for() this one is not safe to call from a scan.
+
+    `available` is passed in rather than looked up. Which colours exist is a
+    question for the terminal driver, and this module sits above the driver:
+    it used to import terminal to ask, which put the settings file underneath
+    the thing that reads it and made the layer order in the README false.
+    """
+    profiles = cfg.setdefault("profiles", {})
+    if name in profiles:
+        return profiles[name]
+    pick = default_profile(name)
+    if pick not in available:
+        pick = "Basic" if "Basic" in available else (next(iter(available), "Basic"))
+    profiles[name] = pick
+    save_config(cfg)
+    return pick

workmap/demo.py

@@ -0,0 +1,94 @@
+"""A throwaway machine to try the first run on.
+
+The first thing a new user sees is the one screen its author can never see
+again, because their machine is already configured. Reproducing it normally
+means deleting your own config, which is a bad enough trade that the screen
+just goes untested and undesigned.
+
+So: build a complete fake home in a temp directory, projects, config, state,
+shell rc, then run the real setup inside it as a child process with HOME
+pointed there. Nothing is stubbed and no code path is special-cased for demo
+mode, which is what makes what you see the actual first run.
+
+PATH is deliberately inherited, so the agents it detects are your real ones.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+# Enough projects that the picker has to sort and number something.
+SAMPLE_PROJECTS = ("acme-api", "acme-web", "marketing-site", "sandbox")
+
+
+def build_home(base: Path, *, projects=SAMPLE_PROJECTS) -> Path:
+    """A believable empty machine: a projects directory and nothing else."""
+    home = base / "home"
+    for name in projects:
+        (home / "dev" / name).mkdir(parents=True, exist_ok=True)
+    (home / ".zshrc").write_text("# a shell rc that was already here\n"
+                                 "export EDITOR=vim\n", encoding="utf-8")
+    return home
+
+
+def child_env(home: Path) -> dict:
+    """The environment the demo runs in.
+
+    HOME does all the work: config, state, rc file and root detection are all
+    derived from it, so one variable moves the entire footprint into the
+    sandbox without workmap needing to know it is being demoed.
+    """
+    env = dict(os.environ)
+    env["HOME"] = str(home)
+    env["SHELL"] = env.get("SHELL", "/bin/zsh")
+    # Roots must be discovered, not inherited: these are what make it a *first*
+    # run rather than this machine's run.
+    env.pop("WORKMAP_ROOTS", None)
+    env.pop("WORKMAP_STATE_DIR", None)
+    env.pop("DEVSTACK_ROOTS", None)
+    return env
+
+
+def run(argv: list[str] | None = None) -> int:
+    argv = list(argv or [])
+    keep = "--keep" in argv
+    base = Path(tempfile.mkdtemp(prefix="workmap-demo-"))
+    home = build_home(base)
+
+    print()
+    print("  This is a practice run on a pretend computer.")
+    print("  Answer anything you like. Your real settings, shell files")
+    print("  and projects are not touched.")
+    print()
+    # The child writes straight to this terminal; flush first or the header
+    # lands after the screens it introduces.
+    sys.stdout.flush()
+
+    try:
+        proc = subprocess.run(
+            [sys.executable, "-m", "workmap.cli", "setup"],
+            env=child_env(home),
+        )
+    except OSError as exc:
+        print(f"  could not start the demo: {exc}", file=sys.stderr)
+        return 1
+    finally:
+        if keep:
+            print()
+            print(f"  The pretend computer is still here: {home}")
+            # HOME alone is not the environment the demo ran in: roots are
+            # read from WORKMAP_ROOTS and DEVSTACK_ROOTS first, so this
+            # command used to show the real machine's projects.
+            print("  Look around it with:")
+            print(f"    env -u WORKMAP_ROOTS -u DEVSTACK_ROOTS "
+                  f"-u WORKMAP_STATE_DIR HOME={home} workmap projects")
+        else:
+            shutil.rmtree(base, ignore_errors=True)
+            print()
+            print("  That was a practice run, so nothing was saved.")
+            print("  Run `workmap setup` when you want to do it for real.")
+    return proc.returncode