use-computer-cli 0.2.1__tar.gz → 0.2.2__tar.gz

{use_computer_cli-0.2.1 → use_computer_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: use-computer-cli
-Version: 0.2.1
+Version: 0.2.2
 Summary: Execute input on a screen for computer-use agents: move, click, drag, scroll, type, key, screenshot.
 Project-URL: Homepage, https://github.com/applica-software-guru/use-computer
 Author: Bruno Fortunato

{use_computer_cli-0.2.1 → use_computer_cli-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "use-computer-cli"
-version = "0.2.1"
+version = "0.2.2"
 description = "Execute input on a screen for computer-use agents: move, click, drag, scroll, type, key, screenshot."
 readme = "README.md"
 requires-python = ">=3.10"

{use_computer_cli-0.2.1 → use_computer_cli-0.2.2}/src/use_computer/cli.py

@@ -48,10 +48,16 @@ from use_computer.actions import (
     TypeAction,
     WindowsAction,
 )
-from use_computer.config import ResolvedConfig, profile_env_var, write_initial_config
+from use_computer.config import (
+    ResolvedConfig,
+    default_screenshot_dir,
+    profile_env_var,
+    write_initial_config,
+)
 from use_computer.config import load as load_config
 from use_computer.coordinates import CoordinateSpace
 from use_computer.errors import UseComputerError
+from use_computer.prune import prune as prune_screenshots
 from use_computer.runner import Session, as_json
 from use_computer.skill import Scope
 from use_computer.skill import install as skill_install
@@ -276,6 +282,22 @@ def _config(
     return resolved
 
 
+def _shared_directory(result: Any) -> Path | None:
+    """The directory every screenshot in this run went to, if they share one.
+
+    A path is 23 tokens and a batch of five verified actions repeats the same directory in every
+    one of them -- 70 tokens of it, five times what the whole closing line costs. Naming it once
+    and printing filenames is the same information for a third of the price.
+    """
+    paths = [
+        item.screenshot.path
+        for item in result.results
+        if item.screenshot is not None and item.screenshot.path is not None
+    ]
+    parents = {path.parent for path in paths}
+    return parents.pop() if len(parents) == 1 and len(paths) > 1 else None
+
+
 def _text_lines(result: Any) -> str:
     """What a run says, as prose: the read, or a line per action.
 
@@ -284,6 +306,7 @@ def _text_lines(result: Any) -> str:
     and a model reads this at a third of the tokens the JSON costs.
     """
     chunks: list[str] = []
+    folder = _shared_directory(result)
     for item in result.results:
         if item.tree is not None:
             if item.tree.text:
@@ -305,7 +328,7 @@ def _text_lines(result: Any) -> str:
             # The path is the answer, and the only part of it worth any tokens.
             shot = item.screenshot
             where = f" {shot.box[2]}x{shot.box[3]} of {shot.of}" if shot.box else ""
-            chunks.append(f"{shot.path}{where}")
+            chunks.append(f"{_shorten(shot.path, folder)}{where}")
             continue
         what = item.action.action
         if item.matched is not None:
@@ -319,10 +342,48 @@ def _text_lines(result: Any) -> str:
         elif item.resolved is not None:
             how = f" at ({item.resolved.x}, {item.resolved.y})"
         done = "would " if not item.performed else ""
-        chunks.append(f"{done}{what}{how} \u2014 {item.duration_ms:.0f} ms")
+        # --verify exists to give feedback, so its answer belongs on the line. `unchanged` is the
+        # word an agent has to notice: it means the coordinate was stale, and it is what stops it
+        # clicking the same wrong pixel forever.
+        verified = ""
+        if item.change is not None:
+            verified = (
+                f" \u2014 changed {item.change.magnitude:.0%}"
+                if item.change.changed
+                else " \u2014 unchanged"
+            )
+        chunks.append(f"{done}{what}{how}{verified} \u2014 {item.duration_ms:.0f} ms")
+        if item.screenshot is not None and item.screenshot.path is not None:
+            # Already captured and already paid for. Saying where saves the agent asking again,
+            # which is the whole reason verify writes it down.
+            chunks.append(f"  {_shorten(item.screenshot.path, folder)}")
+
+    chunks.append(_summary(result, folder))
     return "\n".join(chunks)
 
 
+def _shorten(path: Path | None, folder: Path | None) -> str:
+    """The filename when the directory has already been named, the whole path otherwise."""
+    if path is None:
+        return ""
+    return path.name if folder is not None and path.parent == folder else str(path)
+
+
+def _summary(result: Any, folder: Path | None = None) -> str:
+    """The closing line: everything the envelope carried, for about twenty tokens.
+
+    Cheap must not mean lossy. The envelope was dropped because 177 tokens of braces and repeated
+    keys is a bad price for it, not because the facts in it were worthless -- and the scale in
+    particular is what an agent needs the moment a coordinate lands somewhere surprising.
+    """
+    screen = result.screen
+    scale = f"scale {screen.scale:g}" if screen.scale is not None else "scale unknown"
+    where = f"screen {screen.width}x{screen.height}, {scale}"
+    state = "ok" if result.ok else f"failed at action {(result.failed_index or 0) + 1}"
+    shots = f", screenshots in {folder}" if folder is not None else ""
+    return f"{state} — profile {result.profile}, backend {result.backend}, {where}{shots}"
+
+
 def _run(
     actions: Sequence[Action],
     config: ResolvedConfig,
@@ -749,6 +810,24 @@ app.command("show-menu")(
 )
 
 
+@app.command()
+def prune(
+    keep: Annotated[int, typer.Option("--keep", help="Leave the most recent N.")] = 0,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Say what would go; remove nothing.")
+    ] = False,
+    use: UseOption = None,
+    verbose: VerboseOption = 0,
+) -> None:
+    """Remove the screenshots this tool wrote. Only those, and never the directory."""
+    config = _config(use, verbose=verbose)
+    settings = config.settings
+    directory = settings.screenshot_dir or default_screenshot_dir()
+    result = prune_screenshots(directory, keep=keep, dry_run=dry_run)
+    sys.stdout.write(result.describe() + "\n")
+    raise typer.Exit(EXIT_OK)
+
+
 @app.command()
 def batch(
     source: Annotated[str, typer.Argument(metavar="PATH|-", help="JSON array of actions, or -.")],
@@ -1073,6 +1152,7 @@ _COMMANDS = frozenset(
         "type",
         "key",
         "screenshot",
+        "prune",
         "tree",
         "windows",
         "focus",

{use_computer_cli-0.2.1 → use_computer_cli-0.2.2}/src/use_computer/config.py

@@ -215,15 +215,50 @@ def xdg_data_dir() -> Path:
     return (Path(base) if base else Path.home() / ".local" / "share") / "use-computer"
 
 
+#: Files the tool writes into its own directory that must not be committed. It has always been
+#: documented that `.env` is gitignored and nothing ever made it so.
+GITIGNORE_LINES = ("# written by use-computer", ".env", "screens/")
+
+SCREENS_DIR = "screens"
+
+
 def default_screenshot_dir() -> Path:
     """Where screenshots land when nothing said otherwise.
 
-    The XDG *data* directory: a screenshot of somebody's desktop is not disposable like a cache,
-    and it does not belong in a working tree.
+    Beside the work that produced them when there is a project -- easy to open, easy to throw
+    away, and separate from another project's. Under `.use-computer/` rather than a second hidden
+    directory at the root, because the tool already owns that one.
+
+    Without a project, the XDG *data* directory: a screenshot of somebody's desktop is not
+    disposable like a cache.
     """
+    root = find_project_root()
+    if root is not None:
+        return root / PROJECT_DIR / SCREENS_DIR
     return xdg_data_dir() / "screenshots"
 
 
+def ensure_gitignore(project_dir: Path) -> None:
+    """Keep the tool's own directory out of a commit.
+
+    A screenshot here is the whole desktop -- open conversations, mail, whatever is on it -- and in
+    a working tree one ``git add -A`` commits it. That objection is the reason the docs used to
+    forbid this outright, so the answer travels with the change rather than being left as a note.
+
+    Only ever this directory. Editing the project's own `.gitignore` is the user's business, not a
+    side effect of taking a picture.
+    """
+    path = project_dir / ".gitignore"
+    if path.exists():
+        return
+    try:
+        project_dir.mkdir(parents=True, exist_ok=True)
+        path.write_text("\n".join(GITIGNORE_LINES) + "\n", encoding="utf-8")
+    except OSError:
+        # Not being able to write it must never stop a screenshot being taken.
+        return
+
+
 def env_var_for(field: str) -> str:
     return ENV_PREFIX + field.upper()
 

use_computer_cli-0.2.2/src/use_computer/prune.py

@@ -0,0 +1,95 @@
+"""Removing the screenshots this tool wrote.
+
+CR-004 left it open -- "they are not pruned. The directory grows, and that is the user's to manage
+for now" -- and with the pictures inside the project, for now has run out.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict
+
+#: Exactly the names :meth:`Session._screenshot_path` writes: a sortable UTC stamp, a label, .png.
+#: A pattern rather than "every .png in there", because `screenshot-dir` is configurable and the
+#: first person to point it at their Pictures folder must not lose anything. This tool refuses to
+#: guess everywhere else; it will not guess about deleting.
+OURS = re.compile(r"^\d{8}T\d{6}\.\d{3}Z-[a-z_]+\.png$")
+
+
+class PruneResult(BaseModel):
+    """What a prune did, or would do."""
+
+    model_config = ConfigDict(frozen=True)
+
+    directory: Path
+    removed: tuple[Path, ...] = ()
+    kept: int = 0
+    skipped: int = 0
+    bytes_freed: int = 0
+    performed: bool = True
+
+    def describe(self) -> str:
+        if not self.directory.exists():
+            return f"nothing to remove: {self.directory} does not exist"
+        verb = "removed" if self.performed else "would remove"
+        megabytes = self.bytes_freed / 1_000_000
+        count = len(self.removed)
+        parts = [
+            f"{verb} {count} screenshot{'' if count == 1 else 's'} "
+            f"({megabytes:.1f} MB) from {self.directory}"
+        ]
+        if self.kept:
+            parts.append(f"kept {self.kept}")
+        if self.skipped:
+            # Said out loud: silence here would look like the files had been deleted.
+            noun = "file" if self.skipped == 1 else "files"
+            parts.append(f"left {self.skipped} {noun} this tool did not write")
+        return ", ".join(parts)
+
+
+def ours(path: Path) -> bool:
+    return bool(OURS.match(path.name))
+
+
+def prune(directory: Path, *, keep: int = 0, dry_run: bool = False) -> PruneResult:
+    """Delete the screenshots in ``directory``, newest ``keep`` survive.
+
+    Only files this tool wrote, and never the directory itself. Anything else in there belongs to
+    somebody else and is counted, not touched.
+
+    ``keep`` uses the timestamp in the name rather than the filesystem: the name is the record,
+    which is why it was made to sort.
+    """
+    if not directory.exists():
+        return PruneResult(directory=directory, performed=not dry_run)
+
+    entries = sorted(directory.iterdir())
+    mine = [path for path in entries if path.is_file() and ours(path)]
+    skipped = len([path for path in entries if path.is_file() and not ours(path)])
+
+    doomed = mine[: len(mine) - keep] if keep else mine
+    freed = 0
+    removed: list[Path] = []
+    for path in doomed:
+        size = path.stat().st_size
+        if not dry_run:
+            try:
+                path.unlink()
+            except OSError:
+                continue
+        removed.append(path)
+        freed += size
+
+    return PruneResult(
+        directory=directory,
+        removed=tuple(removed),
+        kept=len(mine) - len(removed),
+        skipped=skipped,
+        bytes_freed=freed,
+        performed=not dry_run,
+    )
+
+
+__all__ = ["PruneResult", "ours", "prune"]

{use_computer_cli-0.2.1 → use_computer_cli-0.2.2}/src/use_computer/runner.py

@@ -41,10 +41,12 @@ from use_computer.actions import (
 from use_computer.backends import Backend, create_backend
 from use_computer.compare import ChangeReport, Screenshot, compare, crop
 from use_computer.config import (
+    PROJECT_DIR,
     BackendProfile,
     ResolvedConfig,
     Settings,
     default_screenshot_dir,
+    ensure_gitignore,
 )
 from use_computer.config import load as load_config
 from use_computer.coordinates import Coordinate, ScreenInfo
@@ -658,7 +660,9 @@ class Session:
         return crop(shot, (left, top, width, height), node_id)
 
     def _screenshot_path(self, label: str) -> Path:
-        """A name that sorts and does not collide."""
+        """A name that sorts and does not collide -- and which `prune` recognises as ours."""
+        if self._screenshot_dir.parent.name == PROJECT_DIR:
+            ensure_gitignore(self._screenshot_dir.parent)
         stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S.%f")[:-3] + "Z"
         return self._screenshot_dir / f"{stamp}-{label}.png"
 

{use_computer_cli-0.2.1 → use_computer_cli-0.2.2}/src/use_computer/skill/SKILL.md

@@ -2,7 +2,7 @@
 name: use-computer
 description: Read and act on a GUI — the accessibility tree of what is on screen (roles, names, clickable boxes), then click, focus, toggle, expand, select, set a value, type, press keys, drag, scroll, screenshot. Locally or over VNC. Ask the tree first and use ui-locator's pixel coordinates only when the tree cannot see the element.
 x-skill-id: use-computer
-x-skill-version: "3"
+x-skill-version: "4"
 ---
 
 # use-computer
@@ -11,7 +11,37 @@ You read and act on a screen through the `use-computer` CLI. It reads the access
 operating system already maintains, and it moves a real pointer and types real keystrokes. It does
 not decide *what* to do — you do.
 
-## Start here: the ladder
+## Two ways to know what is on the screen
+
+They fail in different places, and choosing between them is most of using this tool well.
+
+| | **Structure** (`tree`) | **Pixels** (`screenshot`) |
+| --- | --- | --- |
+| Tells you | roles, names, states, boxes, what is operable | what is *drawn*: painted text, icons, colour, layout |
+| Reaches | things not on screen — a closed menu's items | only what is visible |
+| Costs | a few hundred tokens | an image, and a vision pass |
+| Blind to | anything an app paints instead of exposing | node ids, `enabled`, everything off screen |
+| Acts by | name or id, **with no coordinates at all** | a coordinate you have to aim |
+
+Structure first, always: it is cheaper and it is exact. Go to pixels when structure cannot answer,
+and when you do, **crop to the node** rather than photographing the screen.
+
+### How to move between them
+
+- `reason: unavailable` or `empty` — this application exposes nothing (Qt, Electron, canvas, games
+  do this). A screenshot is already attached to that answer. Go and look.
+- A selector matched nothing — same, and for the same reason. Do not try more selectors.
+- **The tree sees a node but cannot name it.** Two anonymous text fields, say. Do *not* photograph
+  the screen: `screenshot --of <id>` crops to that node. The tree knows exactly *where*; only
+  *what* is missing.
+- Before reaching for pixels at all, two things are usually enough:
+  - **Geometry**, which is already in the tree. A message box is wide and at the bottom; a search
+    box is narrow and near the top. A label sitting to the left of a field, on the same line, names
+    it.
+  - **Focus.** Click one of two identical fields, re-read the tree, and see which now says
+    `!focused`.
+
+## The ladder
 
 Take the highest rung you can reach. Each one is cheaper, faster and more accurate than the one
 below it.
@@ -40,6 +70,13 @@ that still resolves.
 `--format json` returns a JSON envelope instead. You almost never want it: the same answers cost
 three times the tokens, and 177 of those go on the envelope before anything is said.
 
+Every run ends with one line saying whether it worked, which profile and backend answered, the
+screen and the **scale** — `scale unknown` means coordinate conversion will refuse, and is worth
+noticing.
+
+`use-computer <command> --help` lists every flag. This document covers the ones that carry a
+judgement; `--help` covers the rest.
+
 Always pass `--use <profile>` unless a default profile is configured.
 
 ## Coordinates: the thing that goes wrong
@@ -168,8 +205,20 @@ use-computer select --role listitem --name "Italia"
 use-computer show-menu --id 0/1/4
 ```
 
-`--name` is a case-insensitive substring; add `--exact` for equality. `--window` takes
-`focused` (default), `all`, a window title, or `@1234` for a pid.
+`--name` is a case-insensitive substring; add `--exact` for equality, and `--nth N` to pick when
+several match. `--window` takes `focused` (default), `all`, a window title, a window **id**, or
+`@1234` for a pid. `collapse` closes what `expand` opened.
+
+**`--via` chooses which rung**, and is the one flag worth understanding:
+
+- `--via auto` (default) — the platform API if the node supports it, otherwise a click at its
+  centre. Almost always right.
+- `--via action` — refuse rather than fall back. Use it when a coordinate click would be wrong,
+  and note it **works even when the scale is unknown**, because it involves no coordinates.
+- `--via coordinate` — resolve the element, then click it with a real pointer. For interfaces that
+  only respond to genuine input: hover states, drag handles, canvases.
+
+`--delay SECONDS` waits after each action, for an application that needs a moment to catch up.
 
 **Pass `--id` together with `--role` and `--name`** as they came out of `tree`. The id alone is
 just a path, and paths shift when a row is inserted above; with the role and name it is checked,
@@ -279,6 +328,20 @@ follow a verified action with a `screenshot` call. That is the round trip verify
 Verification costs two screenshots per action, so use it on the actions whose effect you need
 to confirm, not on every one.
 
+## Where the pictures go, and getting rid of them
+
+Inside the project, in `.use-computer/screens/`, which the tool keeps out of git for you. Without a
+project, the XDG data directory. A run names the directory once and then just filenames.
+
+```bash
+use-computer prune                # remove them
+use-computer prune --dry-run      # say what would go
+use-computer prune --keep 20      # leave the most recent 20
+```
+
+`prune` only ever removes files this tool wrote, and never the directory. Anything else in there is
+counted and left alone.
+
 ## Before you act on something risky
 
 `--dry-run` resolves and logs everything — profile, scaled coordinates, normalised keys, and the

{use_computer_cli-0.2.1 → use_computer_cli-0.2.2}/tests/test_cli.py

@@ -43,8 +43,8 @@ def runner() -> CliRunner:
     return CliRunner()
 
 
-def invoke(runner: CliRunner, *args: str) -> CliResult:
-    return runner.invoke(app, list(args), catch_exceptions=False)
+def invoke(runner: CliRunner, *args: str, input: str | None = None) -> CliResult:
+    return runner.invoke(app, list(args), catch_exceptions=False, input=input)
 
 
 def test_the_envelope_is_json_and_nothing_else(
@@ -446,20 +446,23 @@ def test_an_action_is_one_line(
     write_config(CONFIG)
     result = invoke(runner, "click", "--role", "button", "--name", "Invia")
     assert result.exit_code == EXIT_OK
-    out = strip_ansi(result.stdout).strip()
-    assert out.count("\n") == 0
-    assert "click button 'Invia' at 0/1/0" in out
-    assert "via the platform API" in out
+    lines = strip_ansi(result.stdout).strip().split("\n")
+    assert len(lines) == 2  # the action, then the closing line
+    assert "click button 'Invia' at 0/1/0" in lines[0]
+    assert "via the platform API" in lines[0]
 
 
-def test_an_error_leaves_stdout_empty(
+def test_a_failure_splits_what_happened_from_why(
     runner: CliRunner, backend: FakeBackend, provider: object, write_config: WriteConfig
 ) -> None:
-    # A reader scrolling back should not have to work out which stream said what.
+    # stdout says what happened, stderr says why. Neither repeats the other, so a reader
+    # scrolling back never has to work out which stream is which.
     write_config(CONFIG)
     result = invoke(runner, "click", "--role", "button")
     assert result.exit_code == EXIT_FAILURE
-    assert strip_ansi(result.stdout).strip() == ""
+    out = strip_ansi(result.stdout).strip()
+    assert out.startswith("failed at action 1")
+    assert "AmbiguousNodeError" not in out
     assert "AmbiguousNodeError" in strip_ansi(result.stderr)
 
 
@@ -471,3 +474,89 @@ def test_the_envelope_is_one_flag_away(
     write_config(CONFIG)
     result = invoke(runner, "windows", "--format", "json")
     assert json.loads(result.stdout)["ok"] is True
+
+
+def test_verify_reports_its_answer_and_where_it_looked(
+    runner: CliRunner, backend: FakeBackend, write_config: WriteConfig
+) -> None:
+    # --verify exists to give feedback. A flag whose whole purpose is feedback must not be silent
+    # in the format everyone gets by default.
+    backend.colours = [(0, 0, 0), (255, 255, 255)]
+    write_config(CONFIG)
+    result = invoke(runner, "click", "--x", "10", "--y", "10", "--verify")
+    assert result.exit_code == EXIT_OK
+    out = strip_ansi(result.stdout)
+    assert "changed" in out
+    assert ".png" in out  # the picture it already paid for, so nobody asks for it twice
+
+
+def test_an_unchanged_screen_says_so_in_a_word(
+    runner: CliRunner, backend: FakeBackend, write_config: WriteConfig
+) -> None:
+    # `unchanged` is the one an agent has to notice: it means the coordinate was stale.
+    backend.colours = [(0, 0, 0), (0, 0, 0)]
+    write_config(CONFIG)
+    result = invoke(runner, "click", "--x", "10", "--y", "10", "--verify")
+    assert "unchanged" in strip_ansi(result.stdout)
+
+
+def test_every_run_ends_with_what_the_envelope_carried(
+    runner: CliRunner, backend: FakeBackend, write_config: WriteConfig
+) -> None:
+    # Cheap must not mean lossy. The envelope was dropped for costing 177 tokens, not because the
+    # facts in it were worthless -- the scale especially, which is what an agent needs the moment
+    # a coordinate lands somewhere surprising.
+    write_config(CONFIG)
+    result = invoke(runner, "click", "--x", "10", "--y", "10")
+    last = strip_ansi(result.stdout).strip().split("\n")[-1]
+    assert last.startswith("ok — ")
+    assert "profile fake" in last
+    assert "backend fake" in last
+    assert "screen 1280x800" in last
+    assert "scale 2" in last
+
+
+def test_a_failure_says_which_action_it_was(
+    runner: CliRunner, backend: FakeBackend, write_config: WriteConfig
+) -> None:
+    write_config(CONFIG)
+    backend.fail_on = "click"
+    result = invoke(runner, "click", "--x", "10", "--y", "10")
+    assert result.exit_code == EXIT_FAILURE
+    assert "failed at action 1" in strip_ansi(result.stdout)
+
+
+def test_an_unknown_scale_is_named_not_omitted(
+    runner: CliRunner, backend: FakeBackend, write_config: WriteConfig
+) -> None:
+    # Refusing to guess a scale is only useful if the caller can see that it is unknown.
+    backend.scale = None
+    write_config(CONFIG)
+    result = invoke(runner, "screenshot")
+    assert "scale unknown" in strip_ansi(result.stdout)
+
+
+def test_a_batch_names_the_screenshot_directory_once(
+    runner: CliRunner, backend: FakeBackend, write_config: WriteConfig, tmp_path: Path
+) -> None:
+    # A path is 23 tokens, and a batch of five verified actions repeats the same directory in
+    # every one of them -- 70 tokens of it, five times what the whole closing line costs.
+    backend.colours = [(0, 0, 0), (255, 255, 255)]
+    write_config(CONFIG)
+    plan = '[{"action":"click","x":1,"y":1},{"action":"click","x":2,"y":2}]'
+    result = invoke(runner, "batch", "-", "--verify", input=plan)
+    out = strip_ansi(result.stdout)
+    assert "screenshots in " in out.split("\n")[-2]
+    for line in out.split("\n"):
+        if line.startswith("  ") and line.strip().endswith(".png"):
+            assert "/" not in line  # a filename, because the directory was already named
+
+
+def test_a_single_screenshot_keeps_its_whole_path(
+    runner: CliRunner, backend: FakeBackend, write_config: WriteConfig
+) -> None:
+    # Nothing to save with one file, and an indirection to read would cost more than it returns.
+    write_config(CONFIG)
+    result = invoke(runner, "screenshot")
+    assert strip_ansi(result.stdout).split("\n")[0].startswith("/")
+    assert "screenshots in " not in strip_ansi(result.stdout)

{use_computer_cli-0.2.1 → use_computer_cli-0.2.2}/tests/test_config.py

@@ -173,14 +173,21 @@ def test_a_profile_field_default_is_reported_like_any_other(write_config: WriteC
     }
 
 
-def test_the_screenshot_directory_defaults_to_the_xdg_data_dir(
-    monkeypatch: pytest.MonkeyPatch,
+def test_without_a_project_the_screenshots_go_to_the_xdg_data_dir(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
     # Never a cache directory: a screenshot of somebody's desktop is not disposable.
+    monkeypatch.chdir(tmp_path)
     monkeypatch.setenv("XDG_DATA_HOME", "/somewhere/data")
     assert default_screenshot_dir() == Path("/somewhere/data/use-computer/screenshots")
 
 
+def test_inside_a_project_they_go_beside_the_config(project: Path) -> None:
+    # Beside the work that produced them, and under the directory this tool already owns rather
+    # than a second hidden one at the root.
+    assert default_screenshot_dir() == project / ".use-computer" / "screens"
+
+
 def test_the_screenshot_directory_is_configurable_like_anything_else(
     write_config: WriteConfig,
 ) -> None:

use_computer_cli-0.2.2/tests/test_prune.py

@@ -0,0 +1,76 @@
+"""Removing screenshots: only the ones this tool wrote, and never the directory."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from use_computer.config import GITIGNORE_LINES, ensure_gitignore
+from use_computer.prune import ours, prune
+
+
+def shot(directory: Path, stamp: str, label: str = "click") -> Path:
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / f"{stamp}-{label}.png"
+    path.write_bytes(b"x" * 10)
+    return path
+
+
+def test_it_recognises_only_the_names_it_writes() -> None:
+    assert ours(Path("20260905T094734.680Z-click.png"))
+    assert ours(Path("20260905T094734.680Z-screenshot.png"))
+    assert not ours(Path("holiday.png"))
+    assert not ours(Path("screenshot.png"))
+    assert not ours(Path("20260905-click.png"))
+
+
+def test_a_file_it_did_not_write_is_counted_and_left(tmp_path: Path) -> None:
+    # `screenshot-dir` is configurable, and the first person to point it at their Pictures folder
+    # must not lose anything. This tool refuses to guess everywhere else.
+    shot(tmp_path, "20260905T094734.680Z")
+    stranger = tmp_path / "holiday.png"
+    stranger.write_bytes(b"mine")
+
+    result = prune(tmp_path)
+    assert len(result.removed) == 1
+    assert result.skipped == 1
+    assert stranger.exists()
+    assert "left 1 file this tool did not write" in result.describe()
+
+
+def test_dry_run_removes_nothing_and_says_so(tmp_path: Path) -> None:
+    kept = shot(tmp_path, "20260905T094734.680Z")
+    result = prune(tmp_path, dry_run=True)
+    assert kept.exists()
+    assert result.performed is False
+    assert result.describe().startswith("would remove 1 screenshot ")
+
+
+def test_keep_leaves_the_most_recent_by_name(tmp_path: Path) -> None:
+    # The name is the record -- which is why it was made to sort -- not the filesystem's mtime.
+    old = shot(tmp_path, "20260905T090000.000Z")
+    new = shot(tmp_path, "20260905T100000.000Z")
+    prune(tmp_path, keep=1)
+    assert new.exists()
+    assert not old.exists()
+
+
+def test_the_directory_itself_survives(tmp_path: Path) -> None:
+    shot(tmp_path, "20260905T094734.680Z")
+    prune(tmp_path)
+    assert tmp_path.exists()
+
+
+def test_a_missing_directory_is_not_an_error(tmp_path: Path) -> None:
+    result = prune(tmp_path / "nowhere")
+    assert result.removed == ()
+    assert "does not exist" in result.describe()
+
+
+def test_the_gitignore_is_written_once_and_never_overwritten(tmp_path: Path) -> None:
+    project = tmp_path / ".use-computer"
+    ensure_gitignore(project)
+    assert (project / ".gitignore").read_text().splitlines() == list(GITIGNORE_LINES)
+
+    (project / ".gitignore").write_text("mine\n")
+    ensure_gitignore(project)
+    assert (project / ".gitignore").read_text() == "mine\n"  # somebody else's, left alone

use_computer_cli-0.2.2/tests/test_skill_is_true.py

@@ -0,0 +1,90 @@
+"""Everything the skill mentions must exist.
+
+The obvious test is the opposite -- assert every command and flag appears in the skill -- and it
+is the wrong direction: it would enforce a second `--help`, longer than the first, that still does
+not say which of two ways to look or what an error means about which to try next.
+
+Rot in the direction of *lying* is what needs catching. A skill that tells an agent to pass
+`--human` after it was removed is actively harmful; one that does not mention `collapse` is merely
+thin, and `--help` covers thin.
+"""
+
+from __future__ import annotations
+
+import re
+
+import pytest
+import typer.main
+
+from use_computer.cli import app
+from use_computer.skill import bundled_text
+
+#: Flags belonging to other tools the skill legitimately shows in shell examples.
+FOREIGN = frozenset(
+    {"--forms", "--add-entry", "--force-renderer-accessibility", "--system-site-packages"}
+)
+
+#: click adds this to every command and never declares it on one.
+UNIVERSAL = frozenset({"--help"})
+
+
+def skill() -> str:
+    return bundled_text()
+
+
+def _walk(group: object, found: set[str], names: set[str]) -> None:
+    for name, command in getattr(group, "commands", {}).items():
+        names.add(name)
+        for parameter in getattr(command, "params", []):
+            found.update(opt for opt in parameter.opts if opt.startswith("--"))
+        _walk(command, found, names)
+
+
+def _surface() -> tuple[set[str], set[str]]:
+    """What the CLI actually declares, from the app itself rather than a hand-kept list.
+
+    A list would drift in exactly the way this test exists to catch.
+    """
+    root = typer.main.get_command(app)
+    options: set[str] = {opt for p in getattr(root, "params", []) for opt in p.opts
+                         if opt.startswith("--")}
+    names: set[str] = set()
+    _walk(root, options, names)
+    return options, names
+
+
+def declared_options() -> set[str]:
+    return _surface()[0]
+
+
+def declared_commands() -> set[str]:
+    return _surface()[1]
+
+
+def test_every_flag_the_skill_mentions_is_real() -> None:
+    mentioned = set(re.findall(r"--[a-z][a-z-]+", skill())) - FOREIGN - UNIVERSAL
+    unknown = mentioned - declared_options()
+    assert not unknown, f"the skill names flags that do not exist: {sorted(unknown)}"
+
+
+def test_every_command_the_skill_shows_is_real() -> None:
+    invoked = set(re.findall(r"^use-computer ([a-z-]+)", skill(), re.M))
+    groups = {"config", "skill"}  # sub-apps, whose own names are checked by their commands
+    unknown = invoked - declared_commands() - groups - {"-"}
+    assert not unknown, f"the skill invokes commands that do not exist: {sorted(unknown)}"
+
+
+@pytest.mark.parametrize("flag", ["--via", "--of", "--format", "--window", "--id"])
+def test_the_flags_that_carry_a_judgement_are_taught(flag: str) -> None:
+    """Not coverage for its own sake: these are the ones `--help` cannot explain.
+
+    `--via` chooses which rung of the ladder an action takes -- the central idea of the tool --
+    and went unmentioned through four revisions of this document.
+    """
+    assert flag in skill()
+
+
+def test_it_teaches_the_two_ways_of_knowing() -> None:
+    text = skill()
+    assert "Structure" in text and "Pixels" in text
+    assert "screenshot --of" in text  # the cheap way down to vision