workmap 0.1.0__py3-none-any.whl

workmap/setup.py

@@ -0,0 +1,400 @@
+"""First run: roots, agents, and the one line that turns on `work`.
+
+Three things have to be true before workmap is useful, and none of them can be
+guessed reliably: where your projects live, which agent you want launched, and
+whether your shell has been told about `work`. Leaving all three to the README
+means most people get a tool that maps an empty desk and never mentions the
+half they'd actually use every day.
+
+Everything here is a plain function over its inputs; `run()` is the only part
+that talks to a person, so the rest is testable.
+"""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+
+from . import config, shell
+from .tui import onboarding as ui
+
+# Command-line coding agents worth looking for. This list only decides what
+# gets *offered*: every entry is checked with shutil.which first, so a name
+# that is wrong or that you have never heard of simply never appears. Anything
+# not here is still usable: type the command at the prompt, or put it under
+# "agents" in the config file.
+AGENT_CANDIDATES = {
+    "claude": "claude",
+    "codex": "codex",
+    "cursor": "cursor-agent",
+    "aider": "aider",
+    "gemini": "gemini",
+    "opencode": "opencode",
+    "goose": "goose",
+    "amp": "amp",
+}
+
+RC_FILES = {
+    "zsh": "~/.zshrc",
+    "bash": "~/.bashrc",
+}
+
+
+def detect_agents(candidates: dict | None = None) -> dict:
+    """Which candidate agents are actually installed here."""
+    found = {}
+    for key, command in (candidates or AGENT_CANDIDATES).items():
+        words = (command or "").split()
+        if words and shutil.which(words[0]):
+            found[key] = command
+    return found
+
+
+def current_shell() -> str:
+    """zsh or bash, from $SHELL. Defaults to zsh, which is the macOS default."""
+    name = Path(os.environ.get("SHELL", "")).name
+    return name if name in shell.SUPPORTED_SHELLS else "zsh"
+
+
+def rc_path(shell_name: str) -> Path:
+    return Path(RC_FILES.get(shell_name, "~/.zshrc")).expanduser()
+
+
+def init_line(shell_name: str, *, name: str = "work") -> str:
+    extra = f" --name {name}" if name != "work" else ""
+    return f'eval "$(workmap shell-init {shell_name}{extra})"'
+
+
+def name_is_taken(name: str, rc: Path) -> bool:
+    """Does the reader already have a command by this name?
+
+    `work` is an ordinary English word and a very ordinary personal alias,
+    which `shell.shell_init` says out loud as the reason `--name` exists.
+    Adding ours on top shadows theirs in every new tab, and the person least
+    able to work out why is the person this screen is written for.
+
+    Two places, because the likely collision is not on PATH. A shell function
+    or alias in their own startup file is what `work` usually is, and
+    `shutil.which` cannot see one.
+    """
+    if shutil.which(name):
+        return True
+    try:
+        body = rc.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    pattern = re.compile(
+        r"^\s*(alias\s+%s=|(function\s+)?%s\s*\(\s*\))" % (re.escape(name),
+                                                           re.escape(name)))
+    # Never read our own line back as a command of theirs, or a second run of
+    # setup renames the command on every pass until it runs out of names.
+    # Redundant while the pattern above only matches `alias x=` and `x()`,
+    # since the line we write is an `eval`, and kept because the day somebody
+    # widens that pattern is the day it stops being redundant.
+    return any(pattern.match(ln) for ln in body.splitlines()
+               if not ln.lstrip().startswith("#")
+               and "workmap shell-init" not in ln)
+
+
+def free_name(rc: Path) -> str:
+    """`work`, or the first thing near it that nobody is using."""
+    for name in ("work", "wm", "wk", "workon"):
+        if not name_is_taken(name, rc):
+            return name
+    return "workmap-work"
+
+
+def already_wired(rc: Path, line: str) -> bool:
+    """Is the init line already live in this rc file? Setup must be re-runnable.
+
+    Live, not merely present. A substring test over the whole file counted a
+    commented-out line, so someone who had switched `work` off by putting a
+    `#` in front of it was told "Already done" and could never switch it back
+    on from here.
+    """
+    try:
+        body = rc.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    return any("workmap shell-init" in ln
+               for ln in body.splitlines() if not ln.lstrip().startswith("#"))
+
+
+def append_init(rc: Path, line: str, *, name: str = "work") -> bool:
+    """Add the init line to an rc file. True if it wrote anything.
+
+    `name` only labels the line. It is what somebody reads when they open
+    their own startup file six months later and want to know what put this
+    here, so it has to be the command they actually got rather than the one
+    it is usually called.
+    """
+    if already_wired(rc, line):
+        return False
+    try:
+        rc.parent.mkdir(parents=True, exist_ok=True)
+        existing = rc.read_text(encoding="utf-8") if rc.exists() else ""
+        prefix = "" if existing.endswith("\n") or not existing else "\n"
+        with open(rc, "a", encoding="utf-8") as fh:
+            fh.write(f"{prefix}\n# workmap: the `{name}` command\n{line}\n")
+        return True
+    except OSError:
+        return False
+
+
+def _setup_roots(interactive: bool) -> list[str]:
+    """Confirm or ask where projects live."""
+    current = ui.spin("Looking for your projects", config.configured_roots)
+    shown = current or config.detect_roots()
+    body = []
+    if shown:
+        body.append(ui.note("Looks like you keep them here:"))
+        body.append("")
+        body += [ui.bullet(ui.path_label(root)) for root in shown]
+        body.append("")
+        body.append(ui.note("Every folder directly inside becomes a project,"))
+        example = ui.path_label(Path(str(shown[0])) / "my-app")
+        body.append(ui.note(f"so {example} shows up as \u201cmy-app\u201d."))
+    else:
+        body.append(ui.warn("We couldn't find a projects folder."))
+        body.append("")
+        body.append(ui.note("Tell us where you keep your code and we'll"))
+        body.append(ui.note("remember it. Something like ~/dev or ~/code."))
+    ui.render(ui.panel("Where do you keep your projects?", body,
+                       step=1, total=3))
+
+    if not interactive:
+        return [str(r) for r in shown]
+
+    if shown:
+        default = ":".join(str(r) for r in shown)
+        answer = ui.ask("Use these?",
+                        enter_does="yes", default=default)
+    else:
+        answer = ui.ask("Where are they?",
+                        enter_does="skip for now", default="")
+
+    chosen = [p for p in answer.split(":") if p]
+    for path in chosen:
+        if not Path(path).expanduser().is_dir():
+            ui.say("    " + ui.warn(f"Heads up: {path} doesn't exist yet."))
+    return chosen
+
+
+def _setup_agents(interactive: bool) -> tuple[dict, str]:
+    """Offer what's installed, and let anything else be typed in."""
+    print()
+    found = ui.spin("Checking what you have installed", detect_agents)
+    missing = [k for k in AGENT_CANDIDATES if k not in found]
+
+    body = []
+    if found:
+        body.append(ui.note("You already have these:"))
+        body.append("")
+        body += [ui.found(key, command) for key, command in found.items()]
+    else:
+        body.append(ui.warn("We didn't find any of the agents we know about."))
+    if missing:
+        body.append("")
+        body.append(ui.listing("Not found: " + ", ".join(missing)))
+    body.append("")
+    body.append(ui.note("Use something else? Type its command instead,"))
+    body.append(ui.note("like \u201caider --model sonnet\u201d. Type \u201cnone\u201d to"))
+    body.append(ui.note("just open the folder without starting anything."))
+    ui.render(ui.panel("Which one should `work` start for you?", body,
+                       step=2, total=3))
+
+    keys = list(found) + ["none"]
+    # Whatever they picked last time, if it is still installed. This used to
+    # be "the first agent that happens to be on PATH", so re-running setup and
+    # pressing Enter, which the screen invites, silently replaced a choice the
+    # user had already made.
+    chosen = config.default_agent()
+    default = chosen if chosen in keys else (keys[0] if keys else "none")
+    if not interactive:
+        return {}, default
+    answer = ui.ask("Which one?", enter_does=default, default=default)
+
+    agents = {}
+    if answer not in keys and answer != "none":
+        # A literal command. Give it a name so it can be picked later.
+        words = answer.split()
+        key = Path(words[0]).name if words else answer
+        if words and not shutil.which(words[0]):
+            ui.say("    " + ui.warn(
+                f"Heads up: {words[0]} isn't installed yet, so `work` will"
+                f" use something else until it is."))
+        agents[key] = answer
+        return agents, key
+    return agents, answer
+
+
+def _a_project_under(roots: list[str]) -> str:
+    """A project name from the roots just chosen.
+
+    Not config.project_dirs(): config.ROOTS is read once at import, so it
+    still holds whatever this process started with, and the closing screen
+    would offer a project from the roots the reader had just replaced.
+    """
+    candidates = roots or [str(r) for r in config.ROOTS]
+    for root in candidates:
+        try:
+            entries = sorted(Path(root).expanduser().iterdir())
+        except OSError:
+            continue
+        for entry in entries:
+            if (not entry.name.startswith(".") and config.addressable(entry.name)
+                    and entry.is_dir()):
+                return entry.name
+    return ""
+
+
+def _setup_shell(interactive: bool) -> tuple[str, Path]:
+    """Returns (what happened, rc_path).
+
+    Three answers, not two. This used to return "needs a new tab" for every
+    path including the one where the user declined, and Enter is the decline:
+    the prompt is `enter_does="skip"`. So the likeliest first run ended on a
+    card headed "you're all set" telling the reader to open a new tab and run
+    `work`, a command that had just not been installed.
+
+        wired    it is in the rc file, this shell has not read it yet
+        already  it was in the rc file before we got here
+        skipped  the reader said no, or we could not write
+    """
+    print()
+    shell_name = current_shell()
+    rc = rc_path(shell_name)
+    line = init_line(shell_name)
+
+    if already_wired(rc, line):
+        ui.render(ui.panel("Switching on the `work` command", [
+            ui.listing(f"Already done. It's in {ui.path_label(rc)}.", ok=True),
+            "",
+            ui.note("Nothing to do here."),
+        ], step=3, total=3))
+        return "already", rc
+
+    # A name nobody is using. `work` is an ordinary word and an ordinary
+    # personal alias, and since Enter now says yes, a reader who has one gets
+    # theirs shadowed in every new tab without having typed anything.
+    name = free_name(rc)
+    line = init_line(shell_name, name=name)
+    body = [
+        ui.note(f"`{name}` moves you into a project folder, and only your"),
+        ui.note("own shell can do that, so it lives in your shell,"),
+        ui.note("not in workmap. It needs this one line:"),
+        "",
+        ui.bullet(line),
+    ]
+    if name != "work":
+        body += [
+            "",
+            ui.warn(f"You already have a `work` command, so this one is"),
+            ui.warn(f"called `{name}` instead. Yours is untouched."),
+        ]
+    body += ["", ui.note(f"We can add it to {ui.path_label(rc)} for you."),
+             ui.note("Nothing else in that file is changed, and taking the"),
+             ui.note("line out again switches it back off.")]
+    ui.render(ui.panel(f"Last thing: switching on `{name}`", body,
+                       step=3, total=3))
+    if not interactive:
+        return "skipped", rc
+    # Enter adds it, like the two questions before this one. It used to skip,
+    # which meant the likeliest guided run, three presses of Enter, ended with
+    # the command the whole tool is named for not installed, and a card
+    # telling the reader to edit a startup file by hand. The screen above
+    # shows the exact line and names the file before asking, so Enter here is
+    # still an answer to a question that was put.
+    if not ui.ask("Add it for you?",
+                  enter_does="yes", default="y").lower().startswith("n"):
+        if append_init(rc, line, name=name):
+            ui.say("    " + ui.listing("Added.", ok=True))
+            return "wired", rc
+        ui.say("    " + ui.warn(
+            f"Couldn't write {ui.path_label(rc)}. Add the line by hand."))
+        return "skipped", rc
+    return "skipped", rc
+
+
+def run(argv: list[str] | None = None) -> int:
+    """Walk through everything workmap needs to know."""
+    interactive = sys.stdin.isatty()
+    print()
+    ui.render(ui.title_card([
+        "Where you keep your projects",
+        "Which agent you want to start",
+        "Switching on the `work` command",
+    ]), stagger=False)
+    if not interactive:
+        ui.say(ui.note("  (Not a terminal, so this is only a preview. "
+                       "Nothing will be saved.)"))
+    print()
+
+    roots = _setup_roots(interactive)
+    agents, default_agent = _setup_agents(interactive)
+    if interactive:
+        cfg = config.load_config()
+        if roots:
+            cfg["roots"] = roots
+        if agents:
+            cfg.setdefault("agents", {}).update(agents)
+        cfg["default_agent"] = default_agent
+        config.save_config(cfg)
+        ui.say("    " + ui.listing(f"Saved to {ui.path_label(config.CONFIG_PATH)}", ok=True))
+    shell_state, rc = _setup_shell(interactive)
+
+    print()
+    # Show a project they actually have, read after the roots were saved: the
+    # module-level ROOTS is frozen at import, so asking config directly would
+    # answer for the roots this process started with rather than the ones the
+    # reader just chose.
+    sample = _a_project_under(roots)
+    rows = []
+    if shell_state == "wired":
+        # Nothing below works in this tab until the shell reloads, so this
+        # goes first and is the only amber thing on the screen.
+        rows += [
+            ui.warn("First, open a new terminal tab."),
+            ui.note(f"Or run:  source {ui.path_label(rc)}"),
+            "",
+        ]
+    if shell_state == "skipped":
+        # The name the step above offered, which is not always `work`: this
+        # card used to print the `work` line regardless, so a reader who had
+        # been shown `wm` was told by hand to install something else.
+        name = free_name(rc)
+        # It was not switched on, so nothing below may suggest typing it.
+        rows += [
+            ui.note(f"`{name}` is not switched on. To do it yourself, add"),
+            ui.note(f"this line to {ui.path_label(rc)}:"),
+            "",
+            ui.bullet(init_line(current_shell(), name=name)),
+            "",
+            ui.note("Then open a new terminal tab. In the meantime:"),
+            "",
+            ui.command("workmap"),
+            ui.command_note("see everything you have open"),
+            "",
+            ui.note("Run `workmap setup` again any time to change this."),
+        ]
+        ui.render(ui.done_card(rows, "one thing left"), stagger=False)
+        print()
+        return 0
+    rows.append(ui.note("Then try:"))
+    rows.append("")
+    rows.append(ui.command("work"))
+    rows.append(ui.command_note("lists your projects, pick one by number"))
+    rows.append("")
+    if sample:
+        rows.append(ui.command(f"work {sample}"))
+        rows.append(ui.command_note("go straight to that one"))
+        rows.append("")
+    rows.append(ui.command("workmap"))
+    rows.append(ui.command_note("see everything you have open"))
+    rows.append("")
+    rows.append(ui.note("Run `workmap setup` again any time to change this."))
+    ui.render(ui.done_card(rows), stagger=False)
+    print()
+    return 0

workmap/shell.py

@@ -0,0 +1,117 @@
+"""The `work` command, as shell source.
+
+workmap can map the desk and colour it, but it cannot put you *in* a project:
+changing directory is something only your own shell can do to itself. So the
+one command that starts work has to be a shell function, and the honest way to
+ship a shell function from a Python package is to print it and have the shell
+evaluate it, the same arrangement zoxide, direnv and pyenv use.
+
+    eval "$(workmap shell-init zsh)"
+
+Everything with real logic in it stays on the Python side, reachable as
+`workmap projects`, `workmap path` and `workmap agent`. What is generated here
+is deliberately thin: a picker, a cd, and a launch. That keeps the part that
+cannot be unit-tested down to the part that cannot be anything else.
+"""
+from __future__ import annotations
+
+SUPPORTED_SHELLS = ("zsh", "bash")
+
+# Words that are already syntax. `if() { ... }` is not a function definition in
+# either shell, it is a parse error, and the generated source is evaluated from
+# the user's rc file, so the cost of accepting one of these is a shell that
+# will not start. str.isidentifier() says yes to all of them, because it is
+# answering a question about Python.
+SHELL_KEYWORDS = frozenset({
+    "if", "then", "elif", "else", "fi", "for", "while", "until", "do", "done",
+    "case", "esac", "select", "function", "in", "time", "coproc", "foreach",
+    "end", "repeat", "nocorrect", "declare", "local", "return", "exit",
+})
+
+# Written to run identically under zsh and bash: POSIX parameter expansion,
+# `read -r`, no arrays, no [[ ]]. One function, two shells, no divergence to
+# keep in step.
+_TEMPLATE = r"""
+# workmap: start work on a project. Generated by `workmap shell-init`.
+{name}() {{
+  # Not `path`: in zsh that name is tied to $PATH, so declaring it
+  # local inside a function empties the command search path and every
+  # command below becomes "not found".
+  local proj="${{1:-}}" agent="${{2:-}}" dir pick n cmd
+
+  if [ -z "$proj" ]; then
+    n=$(workmap projects | wc -l | tr -d ' ')
+    if [ "$n" = "0" ]; then
+      workmap projects   # prints why there are none
+      return 1
+    fi
+    workmap projects | nl -w4 -s') '
+    printf 'Which project? (number or name, Enter to cancel)  '
+    read -r pick || return 1
+    case "$pick" in
+      '')        return 1 ;;
+      *[!0-9]*)  proj="$pick" ;;
+      *)         proj=$(workmap projects | sed -n "${{pick}}p") ;;
+    esac
+  fi
+  [ -z "$proj" ] && return 1
+
+  dir=$(workmap path "$proj") || return 1
+
+  # Optional: bring the project's servers up, if devstack is installed.
+  command -v devstack >/dev/null 2>&1 && devstack up "$proj"
+
+  cd "$dir" || return 1
+
+  if [ -z "$agent" ]; then
+    agent=$(workmap agent --pick) || return 1
+  fi
+
+  # Colour and title the tab. Both are front-tab only and cost no desk scan.
+  workmap paint "$proj" >/dev/null 2>&1
+  workmap title "$proj" "${{agent:-shell}}" >/dev/null 2>&1
+
+  cmd=$(workmap agent --command "$agent") || return 1
+  if [ -n "$cmd" ]; then
+    printf '\033]0;%s\302\267%s\007' "$proj" "${{agent}}"
+    eval "$cmd"
+  fi
+}}
+"""
+
+
+def shell_init(shell: str = "zsh", *, name: str = "work") -> str:
+    """Shell source defining the `work` function.
+
+    `name` exists because `work` is a common enough word to already be taken.
+    On the machine this was written for it was, by an earlier hand-rolled
+    version of exactly this function.
+    """
+    if shell not in SUPPORTED_SHELLS:
+        raise ValueError(
+            f"workmap can't generate a `work` function for {shell}. "
+            f"It knows {' and '.join(SUPPORTED_SHELLS)}."
+        )
+    if not _usable_function_name(name):
+        raise ValueError(
+            f"{name!r} is not a usable shell function name; use letters, "
+            "digits and underscores, starting with a letter or underscore"
+        )
+    if name in SHELL_KEYWORDS:
+        raise ValueError(f"{name!r} is a shell keyword, so it cannot name a "
+                         "function; try something like 'proj'")
+    return _TEMPLATE.format(name=name).lstrip("\n")
+
+
+def _usable_function_name(name: str) -> bool:
+    """ASCII identifier, which is what both shells will reliably parse.
+
+    isidentifier() was the old test and it is the wrong question twice over:
+    it accepts shell keywords, and it accepts every non-ASCII letter Python
+    allows. bash will not define a function whose name is not a valid name in
+    the POSIX sense, so a name that works here and fails there is worse than a
+    name refused in both.
+    """
+    if not name or name[0].isdigit():
+        return False
+    return all(c.isascii() and (c.isalnum() or c == "_") for c in name)

workmap/terminal.py

@@ -0,0 +1,50 @@
+"""The terminal driver, whichever one this machine needs.
+
+Everything above this line in the layer order talks to `terminal.something()`
+and does not know or care which emulator is answering. Everything below it is
+one module per emulator in `drivers/`.
+
+This file used to *be* the Terminal.app driver, which meant the seam the
+README described was really just a promise that nobody had reached past it.
+Now it is a selector: it picks a driver once, at import, from $TERM_PROGRAM,
+and re-exports its contract. Consumers were not changed, because there was
+nothing about them to change, which is the evidence the seam was in the right
+place.
+
+To add an emulator: write `drivers/<name>.py` satisfying `drivers.CONTRACT`,
+add it to `drivers.BY_TERM_PROGRAM`, and make it pass
+`tests/test_driver_contract.py`. Nothing else in the package should need to
+know it exists.
+"""
+from __future__ import annotations
+
+from . import drivers
+
+driver = drivers.for_host()
+
+# The contract, re-exported. Written out rather than star-imported so that
+# reading this file tells you the whole surface, and so a driver that is
+# missing one of these fails at import here rather than at the keypress that
+# happens to need it.
+list_terminal_tabs = driver.list_terminal_tabs
+terminal_status = driver.terminal_status
+owner_pids = driver.owner_pids
+list_profiles = driver.list_profiles
+available_profile_names = driver.available_profile_names
+unsupported_host = driver.unsupported_host
+desktop_bounds = driver.desktop_bounds
+
+set_window_titles = driver.set_window_titles
+set_front_title = driver.set_front_title
+paint_front_window = driver.paint_front_window
+apply_profile = driver.apply_profile
+place_windows = driver.place_windows
+close_windows = driver.close_windows
+focus_window = driver.focus_window
+ensure_title_settings = driver.ensure_title_settings
+
+# Not part of the contract, but the escaping helper is exercised directly by
+# tests and by anyone writing the next driver, so it stays reachable.
+as_string = getattr(driver, "as_string", None)
+
+__all__ = sorted(drivers.CONTRACT) + ["driver", "as_string"]

workmap/themes.py

@@ -0,0 +1,45 @@
+"""Terminal profile names and how each one is drawn.
+
+Three views of one table: hex swatches for anything graphical, a 256-colour
+approximation for the TUI rails, and the order new projects are assigned
+colours in. Depends on nothing, so both config and terminal can read it.
+"""
+from __future__ import annotations
+
+# Curated distinct Terminal profiles + UI swatches (approx).
+PROFILE_SWATCHES = {
+    "Ocean": {"bg": "#0b3d5c", "fg": "#7ec8e3", "rail": "#1f7a9c"},
+    "Grass": {"bg": "#143d1c", "fg": "#8fd19a", "rail": "#2f8f44"},
+    "Homebrew": {"bg": "#0c0c0c", "fg": "#39ff14", "rail": "#1a9e2f"},
+    "Red Sands": {"bg": "#5c2418", "fg": "#f0c0a0", "rail": "#c45a32"},
+    "Pro": {"bg": "#111111", "fg": "#f0f0f0", "rail": "#5a5a5a"},
+    "Novel": {"bg": "#3e3228", "fg": "#efe6d4", "rail": "#8a6a4a"},
+    "Silver Aerogel": {"bg": "#4a4f55", "fg": "#e6e8ea", "rail": "#8b9299"},
+    "Man Page": {"bg": "#5c5428", "fg": "#f5efc8", "rail": "#b5a64a"},
+    "Basic": {"bg": "#f4f4f4", "fg": "#222222", "rail": "#888888"},
+    "Clear Dark": {"bg": "#1a1d22", "fg": "#d7dbe0", "rail": "#6b7280"},
+    "Clear Light": {"bg": "#f0f2f5", "fg": "#222222", "rail": "#9aa3ad"},
+    "Solid Colors": {"bg": "#001a66", "fg": "#ffffff", "rail": "#3355cc"},
+}
+
+# Profile → ANSI 256 (approx of Terminal themes)
+PROFILE_ANSI = {
+    "Ocean": 31,
+    "Grass": 34,
+    "Homebrew": 40,
+    "Red Sands": 166,
+    "Pro": 245,
+    "Novel": 136,
+    "Silver Aerogel": 248,
+    "Man Page": 178,
+    "Basic": 250,
+    "Clear Dark": 240,
+    "Clear Light": 252,
+    "Solid Colors": 27,
+}
+
+# Order in which unseen projects are handed a colour.
+ASSIGN_ORDER = [
+    "Ocean", "Grass", "Red Sands", "Homebrew", "Pro",
+    "Silver Aerogel", "Novel", "Man Page", "Solid Colors", "Clear Dark",
+]

workmap/tui/__init__.py

@@ -0,0 +1,6 @@
+"""The terminal interface.
+
+    text     display-width model and ANSI helpers (pure string maths)
+    widgets  panels, chips and table rows, each an exact display width
+    app      screen state, key handling, frame assembly
+"""