ws-scout 0.1.0__tar.gz

ws_scout-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hokuto Shimura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ws_scout-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: ws-scout
+Version: 0.1.0
+Summary: Scan a workspace of git repos and rank the ones that need attention — triage CLI with LLM-friendly output
+Author: Hokuto Shimura
+License: MIT License
+        
+        Copyright (c) 2026 Hokuto Shimura
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/hoqqun/ws-scout
+Project-URL: Repository, https://github.com/hoqqun/ws-scout
+Project-URL: Issues, https://github.com/hoqqun/ws-scout/issues
+Keywords: git,cli,workspace,multi-repo,triage,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ws-scout
+
+`ws-scout` is a small WSL-friendly CLI that scans `~/workspace`, finds git repositories, and ranks the projects that probably deserve attention.
+
+Unlike most multi-repo status tools, it does not just list repository states: it scores each repository (dirty tree, unpushed commits, TODO notes, recent activity) and sorts them into a triage list, with a `--brief` mode designed to be pasted into an LLM coding assistant as context.
+
+It is useful when the workspace has many active projects and you want a quick morning triage before opening Claude Code.
+
+## What It Checks
+
+- Dirty git working trees
+- Local commits ahead of the remote
+- Branches behind the remote
+- Recent commits
+- TODO/FIXME/HACK notes
+- Common `package.json` scripts
+
+## Usage
+
+```bash
+./ws_scout.py
+./ws_scout.py --brief
+./ws_scout.py --json
+./ws_scout.py ~/workspace --top 20 --depth 2
+```
+
+Install a `ws-scout` command from PyPI:
+
+```bash
+pipx install ws-scout
+# or
+uv tool install ws-scout
+```
+
+Or install from a local checkout:
+
+```bash
+./install.sh
+ws-scout --brief
+```
+
+The `--brief` output is intentionally compact so it can be pasted into Claude Code as context.
+
+## Requirements
+
+- Python 3.10+
+- `git`
+- [ripgrep](https://github.com/BurntSushi/ripgrep) (optional — used for TODO/FIXME scanning; without it the TODO column is simply empty)
+
+## License
+
+[MIT](LICENSE)

ws_scout-0.1.0/README.md

@@ -0,0 +1,52 @@
+# ws-scout
+
+`ws-scout` is a small WSL-friendly CLI that scans `~/workspace`, finds git repositories, and ranks the projects that probably deserve attention.
+
+Unlike most multi-repo status tools, it does not just list repository states: it scores each repository (dirty tree, unpushed commits, TODO notes, recent activity) and sorts them into a triage list, with a `--brief` mode designed to be pasted into an LLM coding assistant as context.
+
+It is useful when the workspace has many active projects and you want a quick morning triage before opening Claude Code.
+
+## What It Checks
+
+- Dirty git working trees
+- Local commits ahead of the remote
+- Branches behind the remote
+- Recent commits
+- TODO/FIXME/HACK notes
+- Common `package.json` scripts
+
+## Usage
+
+```bash
+./ws_scout.py
+./ws_scout.py --brief
+./ws_scout.py --json
+./ws_scout.py ~/workspace --top 20 --depth 2
+```
+
+Install a `ws-scout` command from PyPI:
+
+```bash
+pipx install ws-scout
+# or
+uv tool install ws-scout
+```
+
+Or install from a local checkout:
+
+```bash
+./install.sh
+ws-scout --brief
+```
+
+The `--brief` output is intentionally compact so it can be pasted into Claude Code as context.
+
+## Requirements
+
+- Python 3.10+
+- `git`
+- [ripgrep](https://github.com/BurntSushi/ripgrep) (optional — used for TODO/FIXME scanning; without it the TODO column is simply empty)
+
+## License
+
+[MIT](LICENSE)

ws_scout-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ws-scout"
+version = "0.1.0"
+description = "Scan a workspace of git repos and rank the ones that need attention — triage CLI with LLM-friendly output"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Hokuto Shimura" }]
+requires-python = ">=3.10"
+keywords = ["git", "cli", "workspace", "multi-repo", "triage", "developer-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+
+[project.urls]
+Homepage = "https://github.com/hoqqun/ws-scout"
+Repository = "https://github.com/hoqqun/ws-scout"
+Issues = "https://github.com/hoqqun/ws-scout/issues"
+
+[project.scripts]
+ws-scout = "ws_scout:main"
+
+[tool.setuptools]
+py-modules = ["ws_scout"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

ws_scout-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ws_scout-0.1.0/ws_scout.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: ws-scout
+Version: 0.1.0
+Summary: Scan a workspace of git repos and rank the ones that need attention — triage CLI with LLM-friendly output
+Author: Hokuto Shimura
+License: MIT License
+        
+        Copyright (c) 2026 Hokuto Shimura
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/hoqqun/ws-scout
+Project-URL: Repository, https://github.com/hoqqun/ws-scout
+Project-URL: Issues, https://github.com/hoqqun/ws-scout/issues
+Keywords: git,cli,workspace,multi-repo,triage,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ws-scout
+
+`ws-scout` is a small WSL-friendly CLI that scans `~/workspace`, finds git repositories, and ranks the projects that probably deserve attention.
+
+Unlike most multi-repo status tools, it does not just list repository states: it scores each repository (dirty tree, unpushed commits, TODO notes, recent activity) and sorts them into a triage list, with a `--brief` mode designed to be pasted into an LLM coding assistant as context.
+
+It is useful when the workspace has many active projects and you want a quick morning triage before opening Claude Code.
+
+## What It Checks
+
+- Dirty git working trees
+- Local commits ahead of the remote
+- Branches behind the remote
+- Recent commits
+- TODO/FIXME/HACK notes
+- Common `package.json` scripts
+
+## Usage
+
+```bash
+./ws_scout.py
+./ws_scout.py --brief
+./ws_scout.py --json
+./ws_scout.py ~/workspace --top 20 --depth 2
+```
+
+Install a `ws-scout` command from PyPI:
+
+```bash
+pipx install ws-scout
+# or
+uv tool install ws-scout
+```
+
+Or install from a local checkout:
+
+```bash
+./install.sh
+ws-scout --brief
+```
+
+The `--brief` output is intentionally compact so it can be pasted into Claude Code as context.
+
+## Requirements
+
+- Python 3.10+
+- `git`
+- [ripgrep](https://github.com/BurntSushi/ripgrep) (optional — used for TODO/FIXME scanning; without it the TODO column is simply empty)
+
+## License
+
+[MIT](LICENSE)

ws_scout-0.1.0/ws_scout.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+ws_scout.py
+ws_scout.egg-info/PKG-INFO
+ws_scout.egg-info/SOURCES.txt
+ws_scout.egg-info/dependency_links.txt
+ws_scout.egg-info/entry_points.txt
+ws_scout.egg-info/top_level.txt

ws_scout-0.1.0/ws_scout.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ws_scout-0.1.0/ws_scout.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ws-scout = ws_scout:main

ws_scout-0.1.0/ws_scout.egg-info/top_level.txt

@@ -0,0 +1 @@
+ws_scout

ws_scout-0.1.0/ws_scout.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+"""Fast triage dashboard for a workspace full of git projects."""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import json
+import os
+import subprocess
+import sys
+from collections.abc import Iterable
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+__version__ = "0.1.0"
+
+DEFAULT_IGNORE = {
+    ".cache",
+    ".git",
+    ".next",
+    ".venv",
+    "dist",
+    "node_modules",
+    "target",
+    "tmp",
+    "vendor",
+}
+
+
+@dataclass
+class RepoReport:
+    name: str
+    path: str
+    branch: str | None
+    dirty: bool
+    ahead: int
+    behind: int
+    changed_files: int
+    recent_commit: str | None
+    recent_commit_time: str | None
+    todos: list[str]
+    scripts: list[str]
+    score: int
+    reasons: list[str]
+
+
+def run(cmd: list[str], cwd: Path, timeout: int = 6) -> str:
+    try:
+        proc = subprocess.run(
+            cmd,
+            cwd=str(cwd),
+            text=True,
+            capture_output=True,
+            timeout=timeout,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    return proc.stdout.strip()
+
+
+def parse_porcelain_v2(output: str) -> tuple[int, int, int]:
+    ahead = behind = changed = 0
+    for line in output.splitlines():
+        if line.startswith("# branch.ab "):
+            parts = line.split()
+            for part in parts[2:]:
+                if part.startswith("+"):
+                    ahead = int(part[1:] or "0")
+                elif part.startswith("-"):
+                    behind = int(part[1:] or "0")
+        elif line and not line.startswith("#"):
+            changed += 1
+    return ahead, behind, changed
+
+
+def find_repos(root: Path, max_depth: int, ignore: set[str]) -> list[Path]:
+    repos: list[Path] = []
+    root = root.resolve()
+
+    def walk(path: Path, depth: int) -> None:
+        if depth > max_depth:
+            return
+        if (path / ".git").exists():
+            repos.append(path)
+            return
+        try:
+            children = sorted(path.iterdir(), key=lambda p: p.name.lower())
+        except OSError:
+            return
+        for child in children:
+            if child.name in ignore or child.name.startswith("."):
+                continue
+            if child.is_dir():
+                walk(child, depth + 1)
+
+    walk(root, 0)
+    return repos
+
+
+def recent_todos(path: Path, limit: int) -> list[str]:
+    if limit <= 0:
+        return []
+    rg = [
+        "rg",
+        "--no-heading",
+        "--line-number",
+        "--max-count",
+        str(limit),
+        "--glob",
+        "!**/.venv/**",
+        "--glob",
+        "!**/venv/**",
+        "--glob",
+        "!**/node_modules/**",
+        "--glob",
+        "!**/dist/**",
+        "--glob",
+        "!**/*.ipynb",
+        "-S",
+        r"TODO|FIXME|HACK|XXX",
+        ".",
+    ]
+    out = run(rg, path, timeout=5)
+    lines = []
+    for raw in out.splitlines():
+        if any(part in raw for part in ("/node_modules/", "/.git/", "/dist/", "/venv/", "/.venv/")):
+            continue
+        lines.append(raw[:180])
+        if len(lines) >= limit:
+            break
+    return lines
+
+
+def package_scripts(path: Path) -> list[str]:
+    pkg = path / "package.json"
+    if not pkg.exists():
+        return []
+    try:
+        data = json.loads(pkg.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return []
+    scripts = data.get("scripts")
+    if not isinstance(scripts, dict):
+        return []
+    preferred = ["dev", "start", "build", "test", "lint", "typecheck"]
+    found = [key for key in preferred if key in scripts]
+    extras = sorted(k for k in scripts if k not in found)
+    return found + extras[:4]
+
+
+def inspect_repo(path: Path, root: Path, todo_limit: int) -> RepoReport:
+    branch = run(["git", "branch", "--show-current"], path) or None
+    status = run(["git", "status", "--porcelain=v2", "--branch"], path)
+    ahead, behind, changed = parse_porcelain_v2(status)
+    dirty = changed > 0
+    commit = run(["git", "log", "-1", "--format=%h %s"], path) or None
+    commit_time = run(["git", "log", "-1", "--format=%cI"], path) or None
+    todos = recent_todos(path, todo_limit)
+    scripts = package_scripts(path)
+
+    score = 0
+    reasons: list[str] = []
+    if dirty:
+        score += min(40, 10 + changed * 2)
+        reasons.append(f"{changed} changed file(s)")
+    if ahead:
+        score += 18
+        reasons.append(f"{ahead} commit(s) ahead")
+    if behind:
+        score += 12
+        reasons.append(f"{behind} commit(s) behind")
+    if todos:
+        score += min(15, len(todos) * 3)
+        reasons.append(f"{len(todos)} TODO-like note(s)")
+    if commit_time:
+        try:
+            then = datetime.fromisoformat(commit_time.replace("Z", "+00:00"))
+            age_days = (datetime.now(timezone.utc) - then.astimezone(timezone.utc)).days
+            if age_days <= 2:
+                score += 10
+                reasons.append("recently touched")
+        except ValueError:
+            pass
+
+    return RepoReport(
+        name=path.name,
+        path=str(path.relative_to(root)),
+        branch=branch,
+        dirty=dirty,
+        ahead=ahead,
+        behind=behind,
+        changed_files=changed,
+        recent_commit=commit,
+        recent_commit_time=commit_time,
+        todos=todos,
+        scripts=scripts,
+        score=score,
+        reasons=reasons,
+    )
+
+
+def render_table(reports: Iterable[RepoReport], root: Path) -> str:
+    reports = list(reports)
+    lines = [f"Workspace Scout: {root}", ""]
+    if not reports:
+        return "\n".join(lines + ["No git repositories found."])
+
+    name_w = min(28, max(len(r.name) for r in reports))
+    lines.append(f"{'repo'.ljust(name_w)}  {'branch'.ljust(18)}  score  status")
+    lines.append(f"{'-' * name_w}  {'-' * 18}  -----  ------")
+    for r in reports:
+        branch = (r.branch or "-")[:18].ljust(18)
+        status = ", ".join(r.reasons) if r.reasons else "quiet"
+        lines.append(f"{r.name[:name_w].ljust(name_w)}  {branch}  {r.score:>5}  {status}")
+    return "\n".join(lines)
+
+
+def render_brief(reports: Iterable[RepoReport], root: Path, top: int) -> str:
+    reports = list(reports)[:top]
+    lines = [f"Top workspace items in {root}:"]
+    if not reports:
+        return "No git repositories found."
+    for idx, r in enumerate(reports, 1):
+        reason = ", ".join(r.reasons) if r.reasons else "quiet"
+        lines.append(f"{idx}. {r.name} ({r.branch or '-'}) - {reason}")
+        if r.recent_commit:
+            lines.append(f"   last: {r.recent_commit}")
+        if r.scripts:
+            lines.append(f"   scripts: {', '.join(r.scripts)}")
+        for todo in r.todos[:2]:
+            lines.append(f"   note: {todo}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Scan a workspace and rank git repositories that need attention."
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("root", nargs="?", default="~/workspace", help="workspace root")
+    parser.add_argument("--top", type=int, default=12, help="number of repos to show")
+    parser.add_argument("--depth", type=int, default=2, help="directory search depth")
+    parser.add_argument("--todos", type=int, default=3, help="TODO lines per repo")
+    parser.add_argument("--json", action="store_true", help="emit JSON")
+    parser.add_argument(
+        "--brief",
+        action="store_true",
+        help="emit a compact summary suitable for pasting into Claude Code",
+    )
+    args = parser.parse_args(argv)
+
+    root = Path(os.path.expanduser(args.root)).resolve()
+    if not root.exists():
+        print(f"Root does not exist: {root}", file=sys.stderr)
+        return 2
+
+    repos = find_repos(root, args.depth, DEFAULT_IGNORE)
+    with concurrent.futures.ThreadPoolExecutor(max_workers=min(16, max(1, len(repos)))) as pool:
+        reports = list(pool.map(lambda p: inspect_repo(p, root, args.todos), repos))
+    reports.sort(key=lambda r: (r.score, r.changed_files, r.name.lower()), reverse=True)
+    selected = reports[: max(1, args.top)]
+
+    if args.json:
+        print(json.dumps([asdict(r) for r in selected], ensure_ascii=False, indent=2))
+    elif args.brief:
+        print(render_brief(selected, root, args.top))
+    else:
+        print(render_table(selected, root))
+        print("")
+        print("Tip: run with --brief to paste the summary into Claude Code.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())