workmap 0.1.0__py3-none-any.whl

workmap/cli.py

@@ -0,0 +1,789 @@
+"""Command line entry point: argument routing and the text-mode output.
+
+The interactive map lives in tui/. What a user sees when they type
+`workmap --help` is help_text() below, not this docstring.
+"""
+from __future__ import annotations
+
+import difflib
+import sys
+
+from . import actions, audit, config, layout, scan, shell, terminal
+from . import demo as demo_mod
+from . import setup as setup_mod
+from .config import roots_advice
+from .model import clean_label, fmt_mb, fmt_mem, held_note, plural
+from .tui.text import cell, disp_width
+
+UNNAMED = "unsorted"
+
+# One measure for `workmap list`: a project's name and a session's label are
+# indented differently but both end where the RAM column begins, so the sizes
+# line up under the heading whichever row they are on.
+PROJECT_W = 46
+SESSION_W = PROJECT_W - 2   # sessions are indented two further
+
+# Every word `main` answers to. Used to tell a mistyped command apart from a
+# project name, which is what a bare word otherwise means.
+COMMANDS = (
+    "setup", "demo", "list", "kill", "log", "titles", "title", "paint",
+    "organize", "org", "organize-all", "org-all", "projects", "path", "agent",
+    "shell-init", "help", "version",
+)
+
+# Commands that mean nothing on their own, and what each one is missing. They
+# used to fall through to the branch that reads a bare word as a project name,
+# where `workmap paint` came back as "workmap has no 'paint' command. Did you
+# mean `workmap paint`?", suggesting the thing that had just been typed.
+WANTS_AN_ARGUMENT = {
+    "paint": "a project to paint",
+    "path": "a project to find",
+    "organize": "a project to lay out",
+    "org": "a project to lay out",
+    "title": "a name for the front tab",
+}
+
+
+def unsupported_platform() -> str:
+    """Why workmap cannot read this machine, if it cannot.
+
+    macOS is not a packaging accident here, it is three separate dependencies
+    and only one of them is behind the driver seam:
+
+      drivers/apple_terminal.py  AppleScript. Pluggable: another emulator is a
+                                 new module and nothing else.
+      procs.py                   `top -l 1` for phys_footprint, `vm_stat`,
+                                 `sysctl vm.swapusage`, `lstart` from BSD ps.
+                                 Not syntax. phys_footprint is a macOS idea,
+                                 and the reason the memory numbers are worth
+                                 reading at all.
+      model.is_gui_app           ".app bundle" is a macOS concept, and it is
+                                 what stops the sweep force-quitting a running
+                                 application.
+
+    Without this check the failure was worse than useless: every command
+    degraded quietly to an empty desk and advised the reader to go to System
+    Settings > Privacy & Security > Automation, which does not exist on their
+    computer, and exited 0 as though nothing were wrong.
+    """
+    if sys.platform == "darwin":
+        return ""
+    return (
+        f"workmap only runs on macOS, and this is {sys.platform}.\n"
+        "It reads Terminal.app through AppleScript and measures memory with "
+        "tools that are macOS's own,\nso there is nothing useful it can tell "
+        "you here. Nothing was read and nothing was changed."
+    )
+
+
+def sample_project(fallback: str = "acme-api") -> str:
+    """A project of the user's own to write the examples against.
+
+    Prefers a repository, then anything that reads as a name and fits the
+    column. Both filters earn their place on a real machine: the first
+    directory under the roots here is called "1321", so `workmap kill 1321`
+    read as a command with a number in it rather than an example to copy, and
+    the next was "Music", which is a folder rather than something anyone
+    works on. A checkout is the best available guess at the difference.
+    Falls back to a made-up name only when there is nothing to point at.
+    """
+    def fits(name: str) -> bool:
+        return any(c.isalpha() for c in name) and 3 <= len(name) <= 11
+
+    found = [(n, p) for n, p in config.project_dirs() if fits(n)]
+    for name, path in found:
+        # A directory nobody may traverse answers this with an exception on
+        # Python 3.9, and this runs while building `--help`. One project with
+        # its permissions changed and the tool could not print its own help.
+        try:
+            checked_out = (path / ".git").exists()
+        except OSError:
+            checked_out = False
+        if checked_out:
+            return name
+    if found:
+        return found[0][0]
+    # The last resort has to fit the column too. It did not, so a machine
+    # whose only project was called something long ran the name straight into
+    # the description with no gap between them: the examples are laid out with
+    # `{sample:<14}` and nothing was checking the sample against it.
+    return next((n for n, _ in config.project_dirs() if fits(n)), fallback)
+
+
+def help_text() -> str:
+    """What `workmap --help` prints.
+
+    The examples name a project you actually have wherever one is needed. A
+    placeholder is the thing people type: the setup screen used to end by
+    telling you to run `work`, which takes a project name, and the first
+    person to read it typed `work` and got a list they had not asked for.
+    Costs one directory listing, about 15ms.
+    """
+    sample = sample_project()
+    return f"""\
+workmap: a desk map for the Terminal windows you already have.
+
+Run it with no arguments for the interactive map. Everything else below is a
+one-shot command, so you can pipe it or put it in a script.
+
+  Getting set up
+    workmap setup              say where your projects are, switch on `work`
+    workmap demo               walk through setup on a pretend computer first
+    workmap demo --keep        the same, but leave the pretend computer behind
+
+  Seeing what you have open
+    workmap                    the interactive map
+    workmap list               the same thing as text
+    workmap log                what workmap has quit lately, and what
+                               happened to each one. `workmap log 100` for more
+
+  Quitting what outlived its window
+    workmap kill -n/--dry-run  show what it would quit, and quit nothing
+    workmap kill               quit every orphan
+    workmap kill {sample:<14}quit just that project's orphans
+
+  Tidying the screen
+    workmap {sample:<19}lay its windows out (`organize {sample}`, `org`)
+    workmap organize-all       give every project its own region (`org-all`)
+    workmap titles             rename every window to "project · what"
+    workmap paint {sample:<13}put that project's colour on the front tab
+
+  Starting work (the pieces `work` is built from)
+    workmap projects           every project directory under your roots
+    workmap path {sample:<14}where a project lives
+    workmap agent              which agents you have, and which `work` starts
+    workmap agent codex        start that one from now on
+    workmap agent --pick       ask which one, and print the answer
+    workmap agent --command x  the command line that agent name stands for
+    workmap title {sample:<13}name the front tab, without a desk scan
+    workmap shell-init zsh     print the `work` function, for your shell to
+                               evaluate. Add --name proj if `work` is taken.
+
+Settings live in {config.CONFIG_PATH}.
+Every signal is recorded in {audit.log_path()}."""
+
+
+def flag_value(args: list[str], flag: str, default: str = "") -> str:
+    """The argument after `flag`, or `default` if there isn't one.
+
+    `args[args.index(flag) + 1]` reads past the end whenever the flag is last,
+    which is the ordinary way to find out what a flag wants: type it and press
+    enter. That printed a traceback.
+    """
+    try:
+        i = args.index(flag)
+    except ValueError:
+        return default
+    return args[i + 1] if i + 1 < len(args) else default
+
+
+def without_flag(args: list[str], flag: str) -> list[str]:
+    """`args` with `flag` and the word after it removed, by position.
+
+    Removing them by *value* instead took out any positional that happened to
+    equal the flag's value: `workmap shell-init bash --name bash` lost the
+    shell and silently generated for zsh, and `shell-init fish --name fish`
+    skipped the unsupported-shell check altogether and handed a fish user
+    POSIX source their shell cannot parse.
+    """
+    out: list[str] = []
+    skip = False
+    for arg in args:
+        if skip:
+            skip = False
+            continue
+        if arg == flag:
+            skip = True
+            continue
+        out.append(arg)
+    return out
+
+
+def print_list() -> None:
+    """The desk as text, for reading or piping.
+
+    This used to number the projects, which read like a menu you could pick
+    from and was not one, and it left the orphans unmarked. That is the one
+    distinction the tool exists to draw: an orphan is what `kill` quits, and
+    the snapshot was the one view that would not tell you which lines those
+    were.
+    """
+    snap = scan.snapshot()
+    mem = snap["mem"]
+    projects = snap["projects"]
+    print()
+    orphan_mb = sum(s["mb"] for p in projects
+                    for s in p["sessions"] + p["hidden_sessions"]
+                    if s["kind"] == "bg")
+    # "0M orphaned" is a claim about a machine nobody managed to look at, and
+    # it was printed above the line saying Terminal could not be read.
+    readable = snap["terminal"]["ok"]
+    orphaned = f"   {fmt_mb(orphan_mb)} orphaned" if readable else ""
+    print(f"  workmap   {fmt_mb(snap['tracked_mb'])} in "
+          f"{plural(len(projects), 'project')}{orphaned}"
+          f"   swap {fmt_mem(mem['swap_mb'])}")
+    print()
+
+    advice = terminal.unsupported_host() or roots_advice()
+    if advice:
+        print(f"  {advice}")
+        print()
+
+    if not projects:
+        status = snap["terminal"]
+        if not status["ok"]:
+            # The follow-up belongs to the reason, not to "something failed".
+            # Only one of the driver's failures is a permission problem, and
+            # the Automation instructions were printed for all of them.
+            print(f"  Can't read Terminal: {status['reason']}.")
+            # "Then" only when there is something for it to follow. Half the
+            # driver's failures have no instruction that would help, and this
+            # printed "Terminal automation failed." then "Then run this
+            # again." with nothing between them: a reader assumes they have
+            # missed a line and goes looking for it.
+            if status.get("fix"):
+                print(f"  {status['fix']}")
+                print("  Then run this again.")
+            else:
+                print("  Run this again once it is.")
+        else:
+            print("  Nothing open right now.")
+            print("  Open a Terminal window in a project directory and run")
+            print("  this again, or start one with `work`.")
+        print()
+        return
+
+    print(f"  {cell('PROJECT', PROJECT_W)}{'RAM':>6}  THEME")
+    orphans = 0
+    orphan_total = 0
+    for p in projects:
+        print(f"  {cell(p['name'] or UNNAMED, PROJECT_W)}{fmt_mb(p['mb']):>6}"
+              f"  {p['profile']}")
+        for s in p["sessions"]:
+            # The tag rides with the label rather than in a column of its own.
+            # A separate nine-wide field pushed every session's RAM nine
+            # places right of the project's, and of the RAM heading above
+            # both, so the one column the eye follows down the page did not
+            # line up with itself. Truncate the label, never the tag that
+            # qualifies it, which is what the desk does too.
+            tag = " · orphaned" if s["kind"] == "bg" else ""
+            keep = max(1, SESSION_W - disp_width(tag))
+            print(f"    {cell(clean_label(s['label']), keep)}{tag}"
+                  f"{fmt_mb(s['mb']):>6}".rstrip())
+        if p["hidden_count"]:
+            print(f"    +{p['hidden_count']} more")
+        for s in p["sessions"] + p["hidden_sessions"]:
+            if s["kind"] == "bg":
+                orphans += 1
+                orphan_total += s["mb"]
+        print()
+
+    print(f"  {plural(len(projects), 'project')} open.")
+    if orphans:
+        print(f"  {plural(orphans, 'orphan')} holding "
+              f"{fmt_mb(orphan_total)}: dev servers and agents with no")
+        print("  Terminal window left to close.")
+        print("  See what quitting them would signal:  workmap kill -n")
+        print("  Quit them:                            workmap kill")
+    else:
+        print("  Nothing is running without a window, so there is nothing "
+              "to clean up.")
+    # Said whether or not any orphan was found, because it changes what both
+    # answers mean. An empty list on a machine with a tmux pane holding a dev
+    # server is not the same news as an empty list on a quiet one.
+    if snap.get("held"):
+        print(f"  {snap['held']}")
+    print()
+
+
+def print_log(limit: int = 20) -> None:
+    """What workmap has signalled, most recent last."""
+    records = audit.read_recent(limit * 2)
+    intents = {r["id"]: r for r in records if r.get("event") == "intent"}
+    outcomes = {r["id"]: r for r in records if r.get("event") == "outcome"}
+    if not intents:
+        print()
+        print("  workmap hasn't quit anything yet.")
+        print(f"  When it does, it goes here first: {audit.log_path()}")
+        print()
+        return
+    print()
+    for event_id, intent in (list(intents.items())[-limit:] if limit > 0
+                             else []):
+        done = outcomes.get(event_id)
+        tag = "dry run" if intent.get("dry_run") else "quit"
+        print(f"  {intent['at']}  {tag}  {reason_words(intent['reason'])}  "
+              f"({plural(intent['count'], 'process')})")
+        if done is None:
+            # The intent is written before anything is signalled precisely so
+            # this case can be told apart from a kill that went wrong.
+            print("      No outcome recorded, so workmap did not get as far "
+                  "as signalling these.")
+            continue
+        by_pid = {t["pid"]: t for t in intent.get("targets", [])}
+        for o in done.get("outcomes", []):
+            cmd = by_pid.get(o["pid"], {}).get("cmd", "")
+            print(f"      {o['pid']:>7}  {cell(outcome_words(o), OUTCOME_W)}"
+                  f"{cell(cmd, 43)}".rstrip())
+        print()
+
+
+# What each recorded outcome meant, in words. The stored values are terse
+# because they are a data format; this is the only place they are read by a
+# person, and "skipped-recycled" is not a sentence.
+OUTCOME_W = 21
+
+# Each of these is rendered into OUTCOME_W columns, so each has to fit in
+# them. Two did not: "couldn't check it was still the same" and "no start
+# time recorded" arrived on screen as "couldn't check it wa…" and "no start
+# time record…", which is the one place a reader goes to find out what
+# happened to a process, cut off mid-word.
+OUTCOME_WORDS = {
+    # `sent` and `dry-run` are not here: what they read as depends on which
+    # signal it was, and SIGNAL_WORDS below has both. They were the last two
+    # stored tokens this table was still printing raw.
+    "already-gone": "already gone",
+    "not-permitted": "not ours to signal",
+    "skipped-recycled": "something else had it",
+    "skipped-unchecked": "couldn't be sure",
+    "skipped-protected": "protected",
+    "skipped-unrecorded": "no start time known",
+}
+
+
+# Asking and forcing are not the same thing to anybody, which is why the log
+# records which one it was. Saying "quit" for both would fit the column and
+# lose the distinction the record exists to keep: a process that shut itself
+# down tidily and one that was killed where it stood read alike.
+SIGNAL_WORDS = {
+    "SIGTERM": ("asked to quit", "would ask to quit"),
+    "SIGKILL": ("forced to quit", "would force to quit"),
+}
+
+
+def outcome_words(outcome: dict) -> str:
+    """What a recorded outcome meant, in words, inside OUTCOME_W columns."""
+    result = outcome["result"]
+    if result in ("sent", "dry-run"):
+        asked, would = SIGNAL_WORDS.get(outcome.get("signal") or "",
+                                        ("quit", "would quit"))
+        return would if result == "dry-run" else asked
+    return OUTCOME_WORDS.get(result, result)
+
+
+def reason_words(reason: str) -> str:
+    """What a kill was for, in words. The stored token is data.
+
+    `orphans:acme-web` is a record, not a sentence, and this is the one place a
+    person reads it. The log used to print the token itself, which is how the
+    word the tool stopped using stayed on the screen the README sells as the
+    audit trail.
+    """
+    kind, _, where = reason.partition(":")
+    # `leftovers` is what the token was called before the tool settled on one
+    # word, and records written then are still in the file: eleven of the
+    # twelve on the machine this was found on. They printed raw, so the word
+    # the tool stopped using was on screen anyway, spelled as data.
+    if kind not in ("orphans", "leftovers"):
+        return reason
+    return "orphans everywhere" if where in ("", "all") else f"orphans on {where}"
+
+
+def pick_agent() -> str:
+    """Ask which agent to launch, remembering the answer as the new default.
+
+    The prompt goes to stderr because the caller is a shell function capturing
+    stdout. The only thing on stdout is the answer.
+    """
+    agents = config.available_agents()
+    if not agents:
+        return "none"
+    keys = list(agents) + ["none"]
+    current = config.default_agent()
+    print("Agent:", file=sys.stderr)
+    for i, key in enumerate(keys, 1):
+        mark = "  (default)" if key == current else ""
+        print(f"  {i}) {key}{mark}", file=sys.stderr)
+    print(f"Pick a number or name [Enter={current}]: ", end="", file=sys.stderr)
+    sys.stderr.flush()
+    try:
+        choice = input().strip()
+    except (EOFError, KeyboardInterrupt):
+        print(file=sys.stderr)
+        return current
+    if not choice:
+        choice = current
+    elif choice.isdigit() and 1 <= int(choice) <= len(keys):
+        choice = keys[int(choice) - 1]
+    config.set_default_agent(choice)
+    return choice
+
+
+def print_no_such_project(name: str) -> str:
+    """Why that name did not work, and what would."""
+    known = [n for n, _ in config.project_dirs()]
+    if not known:
+        return (f"There's no project called \"{name}\".\n"
+                + (config.roots_advice() or
+                   "In fact there are no projects yet. Check your roots."))
+    lower = name.lower()
+    # Substring first (typing a fragment is deliberate), then edit distance
+    # for actual typos: "acme-wbe" is not a substring of "acme-web".
+    close = [n for n in known if lower in n.lower() or n.lower() in lower]
+    close += [n for n in difflib.get_close_matches(name, known, n=3, cutoff=0.6)
+              if n not in close]
+    lines = [f"There's no project called \"{name}\"."]
+    if close:
+        lines.append("Did you mean: " + ", ".join(close[:5]) + "?")
+    else:
+        shown = ", ".join(known[:8])
+        more = f", and {len(known) - 8} more" if len(known) > 8 else ""
+        lines.append(f"You have: {shown}{more}")
+    lines.append("Run `work` with no name to pick from a list.")
+    return "\n".join(lines)
+
+
+def print_no_such_agent(name: str) -> str:
+    """Why that agent did not work, and what would."""
+    known = sorted(config.configured_agents())
+    return (f"There's no agent called \"{name}\".\n"
+            f"You have: {', '.join(known)}, or \"none\".\n"
+            f"To add another, put it under \"agents\" in {config.CONFIG_PATH}.")
+
+
+def print_agents() -> None:
+    agents = config.configured_agents()
+    available = config.available_agents()
+    current = config.default_agent()
+    print()
+    print(f"  default: {current}")
+    for key, command in sorted(agents.items()):
+        if key in available:
+            state = ""
+        elif not (command or "").strip():
+            # Setting an agent to "" in the config is how you say no to one,
+            # so reporting it as missing blames the machine for a choice the
+            # reader made. They are the only two reasons a name is on this
+            # list without being offered, and they need different words.
+            state = "   (turned off)"
+        else:
+            state = "   (not installed)"
+        mark = "*" if key == current else " "
+        print(f"  {mark} {key:<10} {command}{state}")
+    print()
+    print(f"  set with: workmap agent <name>   ({config.CONFIG_PATH})")
+    print()
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run one command, then say anything it left to be said.
+
+    The notice is drained here rather than at each of the commands that can
+    raise one, because "did this run rewrite Terminal's settings" is a fact
+    about the process and not about which word was typed. Five commands reach
+    that rewrite and a sixth will be added by somebody who has not read this.
+    """
+    code = _run(argv)
+    notice = actions.take_title_notice()
+    if notice:
+        print(notice)
+    return code
+
+
+def _run(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    if not args:
+        wrong_machine = unsupported_platform()
+        if wrong_machine:
+            print(wrong_machine, file=sys.stderr)
+            return 1
+        from .tui.app import NoTerminalToDrawOn, run
+        try:
+            return run()
+        except NoTerminalToDrawOn as why:
+            # The snapshot is the whole point of the tool, so still print it.
+            print(why, file=sys.stderr)
+            print_list()
+            return 1
+
+    cmd = args[0]
+
+    # Anywhere, not just first. Asking a subcommand what it does is the most
+    # ordinary thing a reader can do, and every one of them took the word as
+    # an argument instead: `workmap setup --help` ran the real setup,
+    # `workmap demo --help` ran the demo, and `workmap kill --help` scanned
+    # the whole desk to report that there is no project called "--help".
+    if cmd in ("-h", "--help", "help") or any(
+            a in ("-h", "--help") for a in args[1:]):
+        print(help_text())
+        return 0
+
+    if cmd in ("-V", "--version", "version"):
+        from . import __version__
+        print(f"workmap {__version__}")
+        return 0
+
+    # Everything below this reads the machine. --help and --version are above
+    # it on purpose: they answer for themselves anywhere, and someone who has
+    # just installed the wrong thing deserves to be able to ask what it was.
+    wrong_machine = unsupported_platform()
+    if wrong_machine:
+        print(wrong_machine, file=sys.stderr)
+        return 1
+
+    if cmd == "setup":
+        return setup_mod.run(args[1:])
+
+    if cmd == "demo":
+        return demo_mod.run(args[1:])
+
+    if cmd == "list":
+        print_list()
+        return 0
+
+    if cmd == "paint" and len(args) >= 2:
+        # Painting remembers the colour, so it writes to the settings file.
+        # Without this check a typo was stored as though it were a project
+        # someone had chosen a colour for, and the file quietly accumulated
+        # every name anyone had ever mistyped. Checking costs a directory
+        # listing and no desk scan.
+        if config.project_path(args[1]) is None:
+            print(print_no_such_project(args[1]), file=sys.stderr)
+            return 1
+        colour = actions.paint_project(args[1])
+        print(f"Front tab is now {colour}, {args[1]}'s colour.")
+        return 0
+
+    if cmd == "titles":
+        n = actions.retitle_all()
+        if not n:
+            print("No Terminal windows to rename.")
+            return 0
+        print(f"Renamed {plural(n, 'Terminal window')} to "
+              f"\"project · what\".")
+        return 0
+
+    if cmd == "kill":
+        rest = [a for a in args[1:] if a not in ("-n", "--dry-run")]
+        dry = len(rest) != len(args) - 1
+        name = rest[0] if rest else None
+        # One scan, used for both the report and the kill. Fetching a second
+        # one to describe what the first is about to signal would mean
+        # printing one set of processes and signalling another, which is the
+        # same mistake kill_sessions() exists to prevent.
+        held: list = []
+        desk = scan.build_projects(held=held)
+        # A name that is not a project reads exactly like a project with
+        # nothing to quit, and `kill` was the one name-taking command that did
+        # not say which it was: `workmap kill acme-wbe` answered "nothing to
+        # quit" and exited 0, which is a false all-clear and a lie to any
+        # script checking the status. A name counts if it is a directory under
+        # a root *or* a project on the desk, because a project can be on the
+        # desk without a directory of its own.
+        if (name is not None and config.project_path(name) is None
+                and not any(config.same_name(p.name, name) for p in desk)):
+            print(print_no_such_project(name), file=sys.stderr)
+            return 1
+        found = scan.background_sessions(name, projects=desk)
+        where = f"on {name}" if name else "across every project"
+        note = held_note(held)
+        if not found:
+            print(f"Nothing is running without a window {where}, so there is "
+                  "nothing to quit.")
+            # The one place an all clear can be a lie. Something recognised is
+            # running and a multiplexer has it, which reads exactly like a
+            # quiet machine and is not one.
+            if note:
+                print(note)
+            return 0
+        result = actions.kill_background(name, projects=desk, dry_run=dry)
+        # What, not how many. A dry run that prints a column of pid numbers
+        # answers the question nobody asked: the reason to run it is to find
+        # out whether the thing about to be signalled is the thing you meant.
+        commands = {}
+        for _, session in found:
+            commands.update(session.cmds)
+        print()
+        print("These have no Terminal window left to close:")
+        print()
+        for outcome in result["outcomes"]:
+            pid = outcome["pid"]
+            what = commands.get(pid, "")
+            print(f"  {pid:>7}  {cell(what, 68)}".rstrip())
+            if outcome["result"] not in ("dry-run", "sent"):
+                print(f"           {outcome['result']}")
+        print()
+        verb = "Would quit" if dry else "Quit"
+        print(f"{verb} {plural(result['sessions'], 'orphan')} {where}, "
+              f"{plural(result['pids'], 'process')}, about "
+              f"{fmt_mb(result['mb'])}.")
+        if note:
+            print(note)
+        if dry:
+            print("Nothing was quit. Run the same command without -n "
+                  "to do it.")
+        else:
+            print(f"Written to {audit.log_path()}; `workmap log` reads it back.")
+        return 0
+
+    if cmd == "log":
+        n = int(args[1]) if len(args) >= 2 and args[1].isdigit() else 20
+        print_log(n)
+        return 0
+
+    # --- the pieces `work` is built from -------------------------------
+    if cmd == "projects":
+        found = config.project_dirs()
+        if not found:
+            advice = config.roots_advice() or (
+                "no project directories under: "
+                + ", ".join(str(r) for r in config.ROOTS)
+            )
+            print(advice, file=sys.stderr)
+            return 1
+        for name, _ in found:
+            print(name)
+        return 0
+
+    if cmd == "path" and len(args) >= 2:
+        path = config.project_path(args[1])
+        if path is None:
+            # A dead end is where a CLI feels unfriendly: say what went wrong
+            # and what to type instead, in the same breath.
+            print(print_no_such_project(args[1]), file=sys.stderr)
+            return 1
+        print(path)
+        return 0
+
+    if cmd == "agent":
+        if "--pick" in args:
+            print(pick_agent())
+            return 0
+        if "--command" in args:
+            key = flag_value(args, "--command")
+            agents = config.available_agents()
+            if key in agents:
+                print(agents[key])
+            elif key and key != "none":
+                # Anything unrecognised is taken literally, so
+                # `work acme-web "npm test"` launches that instead of an agent.
+                print(key)
+            return 0
+        if len(args) >= 2:
+            # Any word used to be written to the config and echoed back as
+            # though it had taken, while default_agent() quietly ignored it
+            # and fell back. The setting said one thing and the tool did
+            # another. `paint` already guards against the same typo.
+            want = args[1]
+            if want != "none" and want not in config.configured_agents():
+                print(print_no_such_agent(want), file=sys.stderr)
+                return 1
+            config.set_default_agent(want)
+            if want == "none":
+                print("`work` now opens the project without starting anything.")
+            elif want in config.available_agents():
+                print(f"`work` now starts {want}.")
+            else:
+                print(f"`work` will start {want} once it is installed. "
+                      f"Until then it starts {config.default_agent()}.")
+            return 0
+        print_agents()
+        return 0
+
+    if cmd == "shell-init":
+        name = flag_value(args, "--name", "work")
+        rest = [a for a in without_flag(args[1:], "--name")
+                if not a.startswith("-")]
+        try:
+            print(shell.shell_init(rest[0] if rest else "zsh", name=name))
+        except (ValueError, IndexError) as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+        return 0
+
+    if cmd in ("organize", "org") and len(args) >= 2:
+        # These used to print the result dict. A caller wants to know what
+        # moved, not what shape the return value is.
+        result = actions.organize_project(args[1])
+        if not result.get("ok"):
+            print(f"Nothing to lay out for {args[1]}: "
+                  f"{result.get('reason', 'no Terminal windows')}.",
+                  file=sys.stderr)
+            return 1
+        stuck = actions.stuck_words(result)
+        if stuck:
+            print(f"Laid out {result.get('placed', 0)} of "
+                  f"{plural(result['windows'], 'window')} for {args[1]}. "
+                  f"{stuck}")
+        else:
+            print(f"Laid {plural(result['windows'], 'window')} out on screen "
+                  f"for {args[1]}.")
+        return 0
+
+    if cmd in ("organize-all", "org-all"):
+        result = actions.organize_all()
+        if not result.get("ok"):
+            print(f"Nothing to lay out: "
+                  f"{result.get('reason', 'no Terminal windows')}.",
+                  file=sys.stderr)
+            return 1
+        stuck = actions.stuck_words(result)
+        print(f"Laid out {plural(result['projects'], 'project')}, each in "
+              f"its own region of the screen ({result['grid']} grid).")
+        if stuck:
+            print(stuck)
+        return 0
+
+    if cmd == "title" and len(args) >= 2:
+        from . import terminal
+        what = args[2] if len(args) >= 3 else "shell"
+        # Cheap path for shell wrappers: title the front tab only, no
+        # profile rewrite and no desk scan.
+        terminal.set_front_title(f"{args[1]} · {what}")
+        print(f"Front tab is now \"{args[1]} · {what}\".")
+        return 0
+
+    # A bare word means a project: lay that project's windows out on screen.
+    # Before paying a second for a desk scan, rule out the likelier reading:
+    # that it was meant to be one of the commands above and got mistyped.
+    # A real command with its argument left off. Answering this as a mistyped
+    # project name is how `workmap paint` came to suggest `workmap paint`.
+    if cmd in WANTS_AN_ARGUMENT:
+        print(f"`workmap {cmd}` needs {WANTS_AN_ARGUMENT[cmd]}. Try: "
+              f"workmap {cmd} {sample_project()}", file=sys.stderr)
+        return 1
+
+    mistyped = difflib.get_close_matches(cmd, COMMANDS, n=1, cutoff=0.7)
+    if mistyped and mistyped[0] == cmd:
+        mistyped = []          # never suggest the word that was just typed
+    if cmd.startswith("-") or (mistyped and config.project_path(cmd) is None):
+        if mistyped:
+            print(f"workmap has no {cmd!r} command. Did you mean "
+                  f"`workmap {mistyped[0]}`?", file=sys.stderr)
+        else:
+            print(f"workmap has no {cmd!r} option. Run `workmap --help` to "
+                  "see what it does understand.", file=sys.stderr)
+        return 1
+
+    hit = next((p for p in scan.build_projects() if p.name == cmd), None)
+    if not hit or not hit.window_ids:
+        if config.project_path(cmd) is None:
+            print(print_no_such_project(cmd), file=sys.stderr)
+        else:
+            print(f"{cmd} has no Terminal windows open, so there is nothing "
+                  f"to lay out. Start one with `work {cmd}`.", file=sys.stderr)
+        return 1
+    moved = layout.gather_windows(hit.window_ids)
+    stuck = actions.stuck_words({"stuck": len(hit.window_ids) - moved})
+    if stuck:
+        print(f"Laid out {moved} of {plural(len(hit.window_ids), 'window')} "
+              f"for {cmd}. {stuck}")
+    else:
+        print(f"Laid {plural(len(hit.window_ids), 'window')} out on screen "
+              f"for {cmd}.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())