fix(cli): reject single-file input cleanly (WI-zujum / UAT BUG-04)

Pointing sketch or run at a file (rather than a directory) previously
printed a helpful hint, then proceeded into generate_sketch and crashed
inside _format_structure_tree_fallback with NotADirectoryError from
Path.iterdir(). The user saw the hint AND a traceback — the opposite
of the intent.

Add an is_dir() guard after the existence check in both cmd_sketch and
cmd_run: print an actionable error pointing at the file's parent
directory, and sys.exit(1). Also fold the existence check into cmd_run
(it was previously missing; cmd_run would crash later with a different
traceback for nonexistent paths).

Signed-off-by: jgstern-agent <josh-agent@iterabloom.com>

Author: jgstern-agent

.ci/affected-tests.txt

@@ -1,8 +1,8 @@
 # Test selection manifest
-# Generated by smart-test at 2026-04-14T09:54:37-04:00
+# Generated by smart-test at 2026-04-14T11:17:40-04:00
 # Mode: targeted
 # Baseline: 3a502998615fa04cbe60be62b61dd38520b9750b
-# Changed files: 15
+# Changed files: 18
 # Changed source files: 5
 # Selected tests: 270
 #

CHANGELOG.md

@@ -13,6 +13,7 @@ This changelog tracks the **tool version** (package releases). The **schema vers
 ### Fixed
 
 - **`-e/--exclude` glob normalization** (WI-zirik / UAT BUG-01): user patterns `ui/`, `ui/**`, `**/ui/**`, `**/ui` now behave consistently with the bare-name form `ui` (per-name fnmatch previously silently dropped any pattern containing `/`). Path-anchored patterns such as `cmd/server.go` are honored against the relative path. Affects both `run` and `sketch`; structure-tree code uses the same normalization.
+- **Single-file input exits cleanly** (WI-zujum / UAT BUG-04): `hypergumbo run` / `sketch` pointed at a file (not a directory) now print an actionable hint and `sys.exit(1)` instead of crashing with `NotADirectoryError` from `Path.iterdir()`. The hint points at the file's parent directory as a likely target.
 
 ### Performance
 

packages/hypergumbo-core/src/hypergumbo_core/cli.py

@@ -573,6 +573,20 @@ def cmd_sketch(args: argparse.Namespace) -> int:
         print(f"Error: path does not exist: {repo_root}", file=sys.stderr)
         return 1
 
+    # WI-zujum: a single-file argument crashes downstream in
+    # _format_structure_tree_fallback (Path.iterdir() raises
+    # NotADirectoryError). Reject early with a hint pointing at the
+    # likely intent — analyse the parent directory.
+    if not repo_root.is_dir():
+        parent = repo_root.parent
+        print(
+            f"Error: {repo_root} is a file, not a directory.\n"
+            f"hypergumbo analyses repositories. Try its parent directory:\n"
+            f"  hypergumbo {parent}",
+            file=sys.stderr,
+        )
+        return 1
+
     # Warn if analyzing a subdirectory of a git repo
     git_root = _find_git_root(repo_root)
     if git_root is not None and git_root.resolve() != repo_root.resolve():
@@ -866,6 +880,22 @@ def cmd_sketch(args: argparse.Namespace) -> int:
 def cmd_run(args: argparse.Namespace) -> int:
     # The positional argument for `run` is called `path` in the parser below.
     repo_root = Path(args.path).resolve()
+
+    # WI-zujum: same single-file guard as cmd_sketch — analysing a single
+    # file is not a supported mode and crashes deeper in the pipeline.
+    if not repo_root.exists():
+        print(f"Error: path does not exist: {repo_root}", file=sys.stderr)
+        return 1
+    if not repo_root.is_dir():
+        parent = repo_root.parent
+        print(
+            f"Error: {repo_root} is a file, not a directory.\n"
+            f"hypergumbo analyses repositories. Try its parent directory:\n"
+            f"  hypergumbo run {parent}",
+            file=sys.stderr,
+        )
+        return 1
+
     out_path = Path(args.out) if args.out else None
     max_tier = getattr(args, "max_tier", None)
     max_files = getattr(args, "max_files", None)

packages/hypergumbo-core/tests/test_cli_commands.py

@@ -2378,6 +2378,65 @@ def test_cmd_sketch_nonexistent_path(capsys) -> None:
     assert "does not exist" in err
 
 
+def test_cmd_sketch_single_file_input_exits_cleanly(tmp_path: Path, capsys) -> None:
+    """Pointing sketch at a file (not a directory) exits cleanly with a hint.
+
+    Per WI-zujum (UAT 2026-04-13 BUG-04): the prior behaviour printed a
+    helpful hint, then proceeded into ``generate_sketch`` and crashed with
+    ``NotADirectoryError`` from ``Path.iterdir()``. The hint must terminate
+    the command so users see the suggestion, not a traceback.
+    """
+    sample = tmp_path / "thing.tla"
+    sample.write_text("---- MODULE Thing ----\n==== ")
+
+    args = FakeArgs()
+    args.path = str(sample)
+    args.tokens = None
+    args.exclude_tests = False
+    args.first_party_priority = True
+    args.extra_excludes = []
+    args.config_extraction_mode = "heuristic"
+
+    result = cmd_sketch(args)
+
+    assert result == 1
+    _, err = capsys.readouterr()
+    assert "directory" in err.lower()
+    assert "thing.tla" in err  # mention what they pointed at
+    # Must not crash with traceback
+    assert "Traceback" not in err
+
+
+def test_cmd_run_nonexistent_path_exits_cleanly(capsys) -> None:
+    """``hypergumbo run /does/not/exist`` exits with a clean error, not a crash."""
+    args = FakeArgs()
+    args.path = "/nonexistent/path/that/does/not/exist"
+    args.out = None
+
+    result = cmd_run(args)
+
+    assert result == 1
+    _, err = capsys.readouterr()
+    assert "does not exist" in err
+
+
+def test_cmd_run_single_file_input_exits_cleanly(tmp_path: Path, capsys) -> None:
+    """``hypergumbo run /path/to/file`` should exit cleanly, not crash."""
+    sample = tmp_path / "thing.tla"
+    sample.write_text("---- MODULE Thing ----\n==== ")
+
+    args = FakeArgs()
+    args.path = str(sample)
+    args.out = None
+
+    result = cmd_run(args)
+
+    assert result == 1
+    _, err = capsys.readouterr()
+    assert "directory" in err.lower()
+    assert "Traceback" not in err
+
+
 def test_cmd_sketch_warns_about_git_root(tmp_path: Path, capsys) -> None:
     """Test cmd_sketch warns when analyzing a subdirectory of a git repo."""
     # Create a git repo structure