workmap 0.1.0__py3-none-any.whl

workmap/__init__.py

@@ -0,0 +1,30 @@
+"""workmap: a desk map for the Terminal windows you already have.
+
+Groups live Terminal.app windows and orphaned background processes by project,
+attributes RAM to each, and gives you one key to clean up.
+
+The layer order lives in ARCHITECTURE.md and is checked by
+`test_scan.Layering`. It was written out here too, and the copy went stale:
+it omitted themes.py and drivers/, and said terminal.py was "the only
+AppleScript in the codebase" long after the driver seam moved every line of
+it into drivers/apple_terminal.py. One place to keep right is enough.
+"""
+from __future__ import annotations
+
+from .model import Project, Session, fmt_mb, fmt_mem
+from .scan import background_sessions, build_projects, snapshot
+from .terminal import terminal_status
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Project",
+    "Session",
+    "background_sessions",
+    "build_projects",
+    "fmt_mb",
+    "fmt_mem",
+    "snapshot",
+    "terminal_status",
+    "__version__",
+]

workmap/__main__.py

@@ -0,0 +1,15 @@
+"""`python3 -m workmap`, for when the installed script is not on PATH.
+
+`install.sh` says so itself when the bin directory is missing from PATH, and
+the next thing a reader tries is the module. Without this they get "'workmap'
+is a package and cannot be directly executed", which reads like a broken
+install rather than a PATH they have not exported yet.
+"""
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

workmap/actions.py

@@ -0,0 +1,350 @@
+"""Everything that changes the world: kill, stop, organize, retitle, recolour.
+
+Every function takes an optional `projects=` scan so a caller that already has
+one doesn't pay for a second. For the kill path it matters more than that:
+it is what makes an action work on exactly the sessions the user was shown."""
+from __future__ import annotations
+
+import subprocess
+
+from . import audit, terminal
+from .config import load_config, remembered_profile, save_config
+from .layout import _usable_desktop, _grid_shape, tile_windows_in_rect
+from .model import Project, Session, plural, short_tool
+from .procs import kill_pids
+from .scan import background_sessions, build_projects
+
+
+# Rewriting twelve of Terminal's built-in profiles is a change to the reader's
+# own application settings, made on their behalf, by a tool they ran once.
+# README.md discloses it in full and nothing on screen did, so somebody who
+# ran ./install.sh and then pressed `o` had no reason to know it had happened.
+TITLE_SETTINGS_NOTICE = (
+    "One thing worth knowing: workmap just turned off Terminal's own window "
+    "titles on its built-in profiles, so it can name windows after your "
+    "projects instead. To put them back, open Terminal, then Settings, then "
+    "Profiles, then the Window tab, and tick the boxes under Title."
+)
+
+# The rewrite outlives the process, so the record of having mentioned it has
+# to as well. A per-process flag would say this again on every single run.
+TOLD_MARKER = "told-about-title-settings"
+
+_title_notice = ""
+
+
+def ensure_titles() -> None:
+    """Turn Terminal's own title bits off, and line up the notice once.
+
+    Said once, because a paragraph repeated on every layout is a paragraph
+    nobody reads. Said again if the marker cannot be written, because at that
+    point we cannot show that we ever said it, and for a disclosure the honest
+    direction to fail in is repeating it rather than dropping it.
+    """
+    global _title_notice
+    terminal.ensure_title_settings()
+    marker = audit.state_dir() / TOLD_MARKER
+    try:
+        if marker.exists():
+            return
+    except OSError:
+        pass
+    _title_notice = TITLE_SETTINGS_NOTICE
+    try:
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.write_text("", encoding="utf-8")
+    except OSError:
+        # Said anyway. See above.
+        pass
+
+
+def take_title_notice() -> str:
+    """The notice, and nothing the next caller can say twice.
+
+    Draining it here is what makes it once per run as well as once per
+    machine: `organize_all` reaches `ensure_titles` through every project on
+    the desk, and the reader needs one paragraph, not one per project.
+    """
+    global _title_notice
+    said, _title_notice = _title_notice, ""
+    return said
+
+
+def stuck_words(result: dict) -> str:
+    """What to tell the reader about windows that would not move, or "".
+
+    One sentence, in one place, because `workmap organize` and the `o` and `O`
+    keys all have to say the same thing and none of them can measure it: only
+    the driver knows, and only after it has asked.
+
+    It names macOS tiling because that is the cause measured on a real
+    machine, and because the reader is holding the tool responsible until
+    something tells them otherwise. It gives the way out first in the form
+    they can do without leaving the keyboard they are at.
+    """
+    stuck = result.get("stuck") or 0
+    if stuck <= 0:
+        return ""
+    one = stuck == 1
+    return (f"macOS is holding {plural(stuck, 'window')} in place, so workmap "
+            f"could not move {'it' if one else 'them'}. Drag "
+            f"{'it out of its tile' if one else 'them out of their tiles'}, "
+            f"or turn tiling off in System Settings, under Desktop and Dock.")
+
+
+def focus_project(project: Project) -> None:
+    if project.window_ids:
+        terminal.focus_window(project.window_ids[0])
+
+
+def ensure_project_profile(name: str, cfg: dict) -> str:
+    """The colour this project is painted in, chosen and remembered once.
+
+    The join between the settings file and the terminal driver, which is what
+    this module is for. config.py holds the preference and terminal.py knows
+    which colours the emulator actually has; neither is allowed to reach for
+    the other, so the pairing happens here.
+    """
+    return remembered_profile(name, cfg, terminal.available_profile_names())
+
+
+def paint_project(name: str, *, all_windows: bool = False,
+                  projects: list[Project] | None = None) -> str | None:
+    """Apply remembered profile.
+
+    Default: paint the front tab only. No full desk scan, no profile-title
+    rewrite. Those are what freeze Terminal when Shell → New Tab is open.
+    Full project paint is opt-in for the TUI.
+
+    The cheap path exists for shell wrappers that call `workmap paint`
+    on every `cd` into a project. No such wrapper ships here.
+    """
+    cfg = load_config()
+    profile = ensure_project_profile(name, cfg)
+    if all_windows:
+        scan = projects if projects is not None else build_projects()
+        hit = next((p for p in scan if p.name == name), None)
+        if hit and hit.window_ids:
+            terminal.apply_profile(hit.window_ids, profile)
+            return profile
+    terminal.paint_front_window(profile)
+    return profile
+
+
+def organize_project(name: str, *, projects: list[Project] | None = None) -> dict:
+    """Tile one project's windows as a group on screen."""
+    ensure_titles()
+    cfg = load_config()
+    profile = ensure_project_profile(name, cfg)
+    scan = projects if projects is not None else build_projects()
+    hit = next((p for p in scan if p.name == name), None)
+    if not hit or not hit.window_ids:
+        return {"ok": False, "reason": "no Terminal windows", "merged": False, "windows": 0}
+
+    titles: dict[int, str] = {}
+    for s in hit.sessions:
+        if s.window_id is None:
+            continue
+        titles[s.window_id] = f"{name} · {short_tool(s.label, s.kind)}"
+    terminal.set_window_titles(titles)
+    terminal.apply_profile(hit.window_ids, profile)
+    ids = hit.window_ids
+
+    left, top, right, bottom = _usable_desktop()
+    placed = tile_windows_in_rect(ids, (left, top, right, bottom), front=True)
+    return {
+        "ok": True,
+        "project": name,
+        "merged": False,
+        "windows": len(ids),
+        "placed": placed,
+        "stuck": len(ids) - placed,
+        "mode": "tiled-group",
+    }
+
+
+def organize_all(*, projects: list[Project] | None = None) -> dict:
+    """Give every project with Terminal windows its own screen region."""
+    ensure_titles()
+    scan = projects if projects is not None else build_projects()
+    scan = [p for p in scan if p.window_ids]
+    if not scan:
+        return {"ok": False, "reason": "no Terminal windows", "projects": 0}
+
+    titles: dict[int, str] = {}
+    for p in scan:
+        for s in p.sessions:
+            if s.window_id is None:
+                continue
+            titles[s.window_id] = f"{p.name} · {short_tool(s.label, s.kind)}"
+    terminal.set_window_titles(titles)
+
+    left, top, right, bottom = _usable_desktop()
+    width = right - left
+    height = bottom - top
+    n = len(scan)
+    rows, cols = _grid_shape(n)
+    cell_w = width // cols
+    cell_h = height // rows
+
+    placed = 0
+    windows = 0
+    moved = 0
+    for i, p in enumerate(scan):
+        terminal.apply_profile(p.window_ids, p.profile)
+        row, col = i // cols, i % cols
+        ids = list(p.window_ids)
+        r = (
+            left + col * cell_w + 3,
+            top + row * cell_h + 3,
+            left + (col + 1) * cell_w - 3,
+            top + (row + 1) * cell_h - 3,
+        )
+        moved += tile_windows_in_rect(ids, r, front=(i == 0))
+        windows += len(ids)
+        placed += 1
+
+    return {"ok": True, "projects": placed, "grid": f"{rows}x{cols}",
+            "windows": windows, "placed": moved, "stuck": windows - moved}
+
+
+def retitle_all(*, projects: list[Project] | None = None) -> int:
+    """Rename every tracked Terminal window to: project · what."""
+    ensure_titles()
+    titles: dict[int, str] = {}
+    for proj in (projects if projects is not None else build_projects()):
+        for s in proj.sessions:
+            if s.window_id is None:
+                continue
+            what = short_tool(s.label, s.kind)
+            titles[s.window_id] = f"{proj.name} · {what}"
+    terminal.set_window_titles(titles)
+    return len(titles)
+
+
+def retitle_project(name: str, *, projects: list[Project] | None = None) -> int:
+    ensure_titles()
+    titles: dict[int, str] = {}
+    for proj in (projects if projects is not None else build_projects()):
+        if proj.name != name:
+            continue
+        for s in proj.sessions:
+            if s.window_id is None:
+                continue
+            what = short_tool(s.label, s.kind)
+            titles[s.window_id] = f"{proj.name} · {what}"
+    terminal.set_window_titles(titles)
+    return len(titles)
+
+
+def set_project_profile(name: str, profile: str, apply: bool = True, *,
+                        projects: list[Project] | None = None) -> Project | None:
+    cfg = load_config()
+    cfg.setdefault("profiles", {})[name] = profile
+    save_config(cfg)
+    scan = projects if projects is not None else build_projects()
+    hit = next((p for p in scan if p.name == name), None)
+    if hit and apply:
+        terminal.apply_profile(hit.window_ids, profile)
+    return hit
+
+
+def kill_sessions(sessions: list[Session], *, reason: str = "kill",
+                  dry_run: bool = False) -> dict:
+    """Kill exactly these sessions: the ones the caller already showed the user.
+
+    This is the honest entry point: the confirmation prompt quotes a count and
+    a size from a scan, and this kills that scan's pids. Re-scanning here (as
+    the old kill_background did) meant you confirmed one set and killed another.
+
+    Every call is written to the audit log, intent first and outcome after, so
+    a kill that goes wrong can be reconstructed afterwards. It is the only
+    place in the package that signals anything, which is what makes one log
+    call enough.
+    """
+    pids: list[int] = []
+    expected: dict[int, str] = {}
+    targets: list[dict] = []
+    for s in sessions:
+        pids.extend(s.pids)
+        expected.update(s.starts)
+        for pid in s.pids:
+            targets.append({"pid": pid, "cmd": s.cmds.get(pid, ""),
+                            "label": s.label, "mb": s.mb})
+
+    event_id = audit.record_intent(reason, targets, dry_run=dry_run)
+    outcomes: list[dict] = []
+    try:
+        signaled = kill_pids(pids, expected, dry_run=dry_run, outcomes=outcomes)
+    finally:
+        audit.record_outcome(event_id, outcomes)
+    return {
+        "sessions": len(sessions),
+        "pids": signaled,
+        "mb": sum(s.mb for s in sessions),
+        "dry_run": dry_run,
+        "event_id": event_id,
+        "outcomes": outcomes,
+    }
+
+
+def kill_background(
+    project_name: str | None = None, *, projects: list[Project] | None = None,
+    dry_run: bool = False,
+) -> dict:
+    """Kill orphaned processes that have no Terminal window.
+
+    project_name=None → all projects. Pass `projects` to act on a scan you
+    already have instead of paying for (and diverging from) a fresh one.
+    """
+    found = background_sessions(project_name, projects=projects)
+    reason = f"orphans:{project_name}" if project_name else "orphans:all"
+    return kill_sessions([s for _, s in found], reason=reason, dry_run=dry_run)
+
+
+def stop_project_stack(name: str, *, projects: list[Project] | None = None,
+                       dry_run: bool = False) -> dict:
+    """Bring a project's servers down, then quit whatever it left behind.
+
+    Servers are stopped by shelling out to `devstack`, which is optional. If
+    it isn't installed we still quit the orphans, and say which half ran
+    rather than reporting success for something that never happened.
+    """
+    stopped, reason = False, ""
+    if dry_run:
+        bg = kill_background(name, projects=projects, dry_run=True)
+        return {"project": name, "servers_stopped": False,
+                "reason": "dry run: devstack not called", "background": bg}
+    try:
+        proc = subprocess.run(
+            ["devstack", "down", name],
+            check=False, capture_output=True, text=True, timeout=60,
+        )
+        stopped = proc.returncode == 0
+        if not stopped:
+            # The other two reasons here are codes the desk translates before
+            # anybody sees them. This one is shown as written, because when
+            # there is output it is the tool's own diagnostic and that is the
+            # useful thing. So the fallback has to read as English and must
+            # not name a program the reader never installed: "devstack failed"
+            # went on screen, in a sentence that had just avoided saying it.
+            reason = (proc.stderr or proc.stdout
+                      or "it exited without saying why").strip()
+    except FileNotFoundError:
+        reason = "devstack not installed"
+    except subprocess.TimeoutExpired:
+        reason = "devstack timed out"
+    except OSError as exc:
+        reason = str(exc)
+    bg = kill_background(name, projects=projects)
+    return {"project": name, "servers_stopped": stopped, "reason": reason,
+            "background": bg}
+
+
+def close_project_windows(name: str, *, projects: list[Project] | None = None) -> int:
+    """Close Terminal windows belonging to a project. Returns count closed."""
+    scan = projects if projects is not None else build_projects()
+    hit = next((p for p in scan if p.name == name), None)
+    if not hit or not hit.window_ids:
+        return 0
+    return terminal.close_windows(hit.window_ids)

workmap/audit.py

@@ -0,0 +1,153 @@
+"""The record of what workmap killed.
+
+Every signal this tool sends is written here before and after it is sent. That
+ordering is the point: a crash between the two leaves an "attempted" line, so
+"we never got that far" and "we killed it and something went wrong" stay
+distinguishable. A process killer with no trail cannot be debugged after the
+fact, which is exactly when you need it.
+
+The log lives outside the source tree and outside the config, in the state
+directory, because it is neither settings nor code. It is JSON Lines: one
+self-contained object per line, append-only, greppable, and safe to truncate
+from the front.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+# Resolved per call, not at import: WORKMAP_STATE_DIR lets a test (or a
+# sandboxed run) redirect the log without monkeypatching module constants.
+# Nothing in the suite may append to the real user's kill history.
+def state_dir() -> Path:
+    override = os.environ.get("WORKMAP_STATE_DIR")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".local" / "state" / "workmap"
+
+
+def log_path() -> Path:
+    return state_dir() / "kills.jsonl"
+
+
+# Keep the file bounded without needing logrotate. Trimming happens on write
+# and keeps the newest records.
+#
+# Bounded by bytes, not by a line count times a guessed line length. One
+# record holds every target's command line, so on this machine they average
+# 3.4 KB and the old 200-byte guess put the "is it worth reading?" gate at
+# about 600 records instead of the 10000 it was aiming for. Past that, every
+# kill read and split the whole file before deciding it had nothing to do.
+MAX_BYTES = 4 * 1024 * 1024
+KEEP_BYTES = MAX_BYTES // 2
+MAX_LINES = 5000
+
+
+def _write(record: dict) -> None:
+    """Append one record. Never raises: logging must not block a kill."""
+    try:
+        path = log_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        line = json.dumps(record, sort_keys=True, default=str)
+        with open(path, "a", encoding="utf-8") as fh:
+            fh.write(line + "\n")
+        _trim_if_huge(path)
+    except OSError:
+        pass
+
+
+def _trim_if_huge(path: Path) -> None:
+    """Drop the oldest records once the file gets large.
+
+    Cut back to half the ceiling rather than to just under it, so this runs
+    rarely instead of on every write from the moment the limit is first
+    reached.
+    """
+    try:
+        if not path.exists() or path.stat().st_size < MAX_BYTES:
+            return
+        lines = path.read_text(encoding="utf-8").splitlines()
+        keep: list[str] = []
+        total = 0
+        for line in reversed(lines):
+            total += len(line.encode("utf-8")) + 1
+            if keep and (total > KEEP_BYTES or len(keep) >= MAX_LINES):
+                break
+            keep.append(line)
+        keep.reverse()
+        tmp = path.with_suffix(".jsonl.tmp")
+        tmp.write_text("\n".join(keep) + "\n", encoding="utf-8")
+        os.replace(tmp, path)
+    except OSError:
+        pass
+
+
+# Two records written in the same millisecond by the same process used to get
+# the same id, and `workmap log` pairs intents to outcomes by id: colliding
+# records overwrite each other, so the log showed fewer kills than happened
+# and could file one kill's outcome under another's intent. Twenty in a loop
+# came back as two. A counter costs nothing and the id only has to be unique,
+# not meaningful; the timestamp is still in there for reading by eye.
+_event_seq = 0
+
+
+def _next_event_id() -> str:
+    global _event_seq
+    _event_seq += 1
+    return f"{int(time.time() * 1000)}-{os.getpid()}-{_event_seq}"
+
+
+def record_intent(reason: str, targets: list[dict], *, dry_run: bool) -> str:
+    """Note what is about to be signalled, before anything is signalled.
+
+    Returns an id that ties this to the outcome record. `targets` is one dict
+    per pid: {"pid", "cmd", "project", "label"}.
+    """
+    event_id = _next_event_id()
+    _write({
+        "event": "intent",
+        "id": event_id,
+        "at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "reason": reason,
+        "dry_run": dry_run,
+        "count": len(targets),
+        "targets": targets,
+    })
+    return event_id
+
+
+def record_outcome(event_id: str, outcomes: list[dict]) -> None:
+    """Note what actually happened to each pid.
+
+    `outcomes` is one dict per pid: {"pid", "signal", "result"} where result is
+    one of sent / already-gone / not-permitted / skipped-recycled /
+    skipped-unchecked / skipped-protected / dry-run.
+    """
+    _write({
+        "event": "outcome",
+        "id": event_id,
+        "at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "count": len(outcomes),
+        "outcomes": outcomes,
+    })
+
+
+def read_recent(limit: int = 20) -> list[dict]:
+    """The most recent records, newest last. For `workmap log`."""
+    if limit <= 0:
+        # `lines[-0:]` is the whole list, so `workmap log 0` printed every
+        # record it had rather than none.
+        return []
+    try:
+        lines = log_path().read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return []
+    out: list[dict] = []
+    for line in lines[-limit:]:
+        try:
+            out.append(json.loads(line))
+        except ValueError:
+            continue
+    return out