gitroster 0.2.0__py3-none-any.whl

gitroster/store.py

@@ -0,0 +1,80 @@
+"""Small JSON persistence: user notes/flags and the last scan."""
+import hashlib
+import json
+import os
+import sys
+import threading
+from pathlib import Path
+
+
+def _dir(kind):
+    """Per-OS config/state folder: XDG on Linux, Application Support on macOS, AppData on Windows."""
+    home = Path.home()
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA" if kind == "config" else "LOCALAPPDATA") or str(home / "AppData" / ("Roaming" if kind == "config" else "Local"))
+    elif sys.platform == "darwin":
+        base = str(home / "Library" / "Application Support")
+    else:
+        base = os.environ.get("XDG_CONFIG_HOME" if kind == "config" else "XDG_STATE_HOME") or str(home / (".config" if kind == "config" else ".local/state"))
+    d = Path(base) / "gitroster"
+    if sys.platform in ("win32", "darwin") and kind == "state":
+        d = d / "state"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+class Store:
+    def __init__(self, config_dir=None, state_dir=None):
+        self.config = Path(config_dir) if config_dir else _dir("config")
+        self.state = Path(state_dir) if state_dir else _dir("state")
+        self.config.mkdir(parents=True, exist_ok=True)
+        self.state.mkdir(parents=True, exist_ok=True)
+        self.lock = threading.Lock()
+
+    def _load(self, path):
+        try:
+            return json.loads(path.read_text())
+        except (OSError, ValueError):
+            return {}
+
+    def _save(self, path, data):
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(data))
+        tmp.replace(path)
+
+    def meta(self):
+        return self._load(self.config / "meta.json")
+
+    def update_meta(self, repo_path, **fields):
+        allowed = {"note", "pinned", "ignored", "summary"}
+        with self.lock:
+            data = self._load(self.config / "meta.json")
+            entry = data.setdefault(repo_path, {})
+            entry.update({k: v for k, v in fields.items() if k in allowed})
+            self._save(self.config / "meta.json", data)
+            return entry
+
+    def settings(self):
+        return self._load(self.config / "settings.json")
+
+    def update_settings(self, **fields):
+        allowed = {"editor", "editor_custom", "terminal", "theme", "agent", "agent_custom"}
+        with self.lock:
+            data = self._load(self.config / "settings.json")
+            data.update({k: v for k, v in fields.items() if k in allowed})
+            self._save(self.config / "settings.json", data)
+            return data
+
+    def cached_scan(self):
+        return self._load(self.state / "scan.json")
+
+    def save_scan(self, scan):
+        with self.lock:
+            self._save(self.state / "scan.json", scan)
+
+    def log_path(self, repo_path):
+        """One log per repo folder; the hash keeps two repos with the same folder name apart."""
+        d = self.state / "logs"
+        d.mkdir(exist_ok=True)
+        key = hashlib.sha1(str(repo_path).encode()).hexdigest()[:8]
+        return d / f"{Path(repo_path).name}-{key}.log"

gitroster-0.2.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: gitroster
+Version: 0.2.0
+Summary: Find the repos, virtual envs and open ports you forgot about, and how to run them.
+Author: firatsahn
+License: MIT
+Project-URL: Homepage, https://github.com/firatsahn/gitroster
+Project-URL: Source, https://github.com/firatsahn/gitroster
+Project-URL: Issues, https://github.com/firatsahn/gitroster/issues
+Project-URL: Changelog, https://github.com/firatsahn/gitroster/blob/main/CHANGELOG.md
+Keywords: developer-tools,git,ports,virtualenv,dashboard,local-first
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/firatsahn/gitroster/main/gitroster/static/icon.svg" width="72" alt="gitroster logo">
+</p>
+
+<h1 align="center">gitroster</h1>
+
+<p align="center">
+  <b>A roster of every git repo on your machine: yours, forks and clones.<br>What each one is, what's running, and how to run it.</b>
+</p>
+
+---
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/firatsahn/gitroster/main/docs/home-light.png" alt="gitroster: a list of repos with running ports, uncommitted work, an AI summary and a note" width="860">
+</p>
+
+You clone a lot of open source projects, fork some, and write your own. Months later you have no idea which ones are still on disk, which are running in the background, which port belongs to what, or how you started them. gitroster scans your folders and puts it all on one page.
+
+## Quick start (web, recommended)
+
+```bash
+pip install gitroster         # or: pipx install gitroster
+gitroster ~/projects          # then open http://127.0.0.1:8765
+```
+
+From source, without installing:
+
+```bash
+git clone https://github.com/firatsahn/gitroster && cd gitroster
+python3 -m gitroster ~/projects
+```
+
+Want to look around first? `gitroster --demo` shows sample repos and touches nothing on your machine. Running, stopping and opening are switched off in the demo.
+
+### Desktop app (Electron)
+
+Prefer a window over a browser tab? The same UI runs in an Electron shell on Windows, macOS and Linux:
+
+```bash
+cd electron && npm install && npm start
+```
+
+It starts the local server on a free port and stops it when you close the window. It needs Python 3.9+ on the machine (set `GITROSTER_PYTHON` if it is not on your PATH). It scans `~/projects`, or your home folder if that does not exist; set `GITROSTER_ROOTS` to scan other folders. `npm run dist` builds an installer with electron-builder.
+
+### Platforms
+
+Linux, macOS and Windows are supported. Ports come from `ss` (Linux), `lsof` (macOS) or `netstat` (Windows). On Windows a process's working directory is not readable, so ports are matched to repos by the command line only.
+
+Scan several folders at once with `gitroster ~/projects ~/tools`. Without arguments it scans your home folder. Use `gitroster --json` to print a scan for scripts.
+
+## What you get
+
+**Repos**
+- Every git repo, with last commit, branch, size on disk and README summary
+- Sorted by origin: **mine** (you authored commits), **fork** (has an `upstream` remote), **clone** (someone else's) and **local** (no remote)
+- Flags for **uncommitted changes**, **unpushed commits**, **no remote** and **dormant** (no commit in 90+ days and nothing running)
+- Notes, pin and ignore, kept in `~/.config/gitroster/` (`~/Library/Application Support/gitroster` on macOS, `%APPDATA%\gitroster` on Windows)
+
+**Look inside any repo**
+- A detail page per repo: overview (languages, contributors linked to GitHub, tags, most changed files, README), file browser with a viewer, commit history with a graph and per-commit diffs, branches, dependencies
+- **Search** code, file names and commit messages across every repo at once (plain text or regex)
+- Search also finds **packages**: which repo uses a package and at which version, flagged when versions differ between repos
+- **Related repos**: copies of the same remote, and local repos that depend on each other
+- Everything is read-only
+
+**Work you might forget**
+- Stashes, branches that exist only on this machine or are not merged yet, and extra worktrees, with filters for each
+- A commit graph of every branch (click a branch to jump to it)
+- Light, dark or system theme in Settings
+- One-click open in your editor, terminal or file manager. Settings lists the editors (VS Code, Cursor, PyCharm, IntelliJ, Zed, Sublime and more) and terminals installed on your machine so you can pick one, or set a custom command
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/firatsahn/gitroster/main/docs/detail.png" alt="Repo detail page with an AI summary, languages, contributors and most changed files" width="860">
+</p>
+
+**How to run it**
+- Setup and run commands detected from `package.json` (npm, pnpm, yarn), `pyproject.toml`, `requirements.txt`, `manage.py`, `main.py`/`app.py`, `Cargo.toml`, `go.mod`, `pubspec.yaml`, `Makefile`, Docker Compose and Wrangler
+- Commands use the repo's own virtual environment when one exists
+- Commands and ports mentioned in the README
+- **▶ Start** runs a detected command in the background with a log (after you confirm)
+
+**Ports and processes**
+- Every listening port you own, matched to a repo by the process working directory, then by the command line
+- Ports open on all interfaces are flagged
+- One click to open it in the browser, one to stop it
+- Docker containers, matched to their compose folder
+
+**AI summary (optional)**
+- Press the sparkle button next to **Details** and an agent CLI you already have writes a short summary of the repo: what it is, stack, how to run it, what you were working on, gotchas. It is labelled *AI-generated, unverified*, shown on the card and on the repo's Overview, and marked when the repo has changed since.
+- gitroster finds the agent CLIs installed on your machine (Claude Code, Codex CLI, Gemini CLI) and you pick one in Settings. There is no API key to enter and no model to host: it runs the CLI you are already signed in to, with its tools turned off, and nothing is executed.
+- It sends that agent the README, a file list (secret-looking files are left out), dependency names, detected commands and recent commit titles. Where that goes depends on the agent: all three are cloud services.
+- Prefer another tool? Use any command that reads a prompt on stdin: a custom command in Settings, `gitroster --agent-cmd "my-agent"` or `GITROSTER_AGENT`.
+- Only Claude Code is tested here. The Codex and Gemini invocations follow their documented non-interactive modes but are untested.
+
+## How it works
+
+Detection is deterministic: file checks, `git`, `du`, `ss` and `/proc`. The AI part is opt-in and separate. See [SECURITY.md](SECURITY.md) for the safety model: loopback only, host and origin checks, and start/stop limited to things the scanner found.
+
+## Limits
+
+- Linux, macOS and Windows. On Windows a process's working directory is not readable, so ports are matched by command line only.
+- Only processes owned by your user are visible.
+- Hidden folders (`~/.nvm`), `node_modules` and anything deeper than 6 levels are skipped.
+- A big first scan can take a while on slow disks or `/mnt/c`. The last result is shown instantly while a new scan runs.
+- Run commands are guesses from well-known files. Treat them as a starting point.
+
+## Contributing
+
+Issues and PRs welcome, see [CONTRIBUTING.md](CONTRIBUTING.md). Run the tests with `python3 -m unittest discover -s tests`.
+
+## License
+
+MIT

gitroster-0.2.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+gitroster/__init__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+gitroster/__main__.py,sha256=xs0ncFDq0tEcmLfLq5Gtp9GeSVyV5Mht4fmq8rIFHTg,51
+gitroster/agent.py,sha256=MK2adQh15OKYfL4xZssPWx-pwswTHFnz1CdukMuFQbY,6611
+gitroster/cli.py,sha256=12Qt9jhTBIM-mJ42eVQGMkQmJ_AMmIuMr_TIQKzNFpQ,1641
+gitroster/demo.py,sha256=8bZUpabF1SHwt50WGdLKahGv8lxv2sh35PxcyikA8zw,7321
+gitroster/deps.py,sha256=IiRuLNK356CpsYm1fnjxJxTAdgU0kBp-sL1jiT_V13s,7095
+gitroster/export.py,sha256=Bpvh0WbwLqRQzF4vPBctiOmMRYDt8RnN8ai1vGXbe2w,1844
+gitroster/opener.py,sha256=cQZ_IpUCxe3Mr9Ij4N_JzVjH7VTI6sg0H0QCOxkSHjA,8121
+gitroster/pathscan.py,sha256=k4IpL5Q6w-yoqZL4QGDtBwUScBzRO1mDW6jUslUaRzM,1140
+gitroster/procs.py,sha256=-fWI4wgwcJQ91EJaUA8ba_I0RWqNLZrIN5MHk6hypoU,6337
+gitroster/repoinfo.py,sha256=bykR3ALQqRMHCEEqTPNkQ1qfGZVOmOHuCR6LFO9LTRc,9860
+gitroster/scanner.py,sha256=lENKEsOdwufuXX8TAjdgJvw0d65Ni0nFLtYLKpC3Df4,18783
+gitroster/server.py,sha256=kX5BMjOgnjEplgCwfNorEREFN_Vb7AksO3fvRBHniEo,10867
+gitroster/store.py,sha256=_BzCIJCq_yp7q_hacblDd3svt2IE3aZaKHYgp6-gCkw,3013
+gitroster/static/icon.svg,sha256=d7a428MCnphLgCwBEmkKko0q3NoCm5rj2Jy1_fOl6xs,691
+gitroster/static/index.html,sha256=iJ4xanPJ1a2mXmTm88XB1HVJd-HQXeLXcXU2u_axAoo,68118
+gitroster-0.2.0.dist-info/licenses/LICENSE,sha256=cNk0zyV12h_cZTh6A31XoE-C3c1VyLFxWeKXvrg8-Fg,1079
+gitroster-0.2.0.dist-info/METADATA,sha256=PCrySht3Bx5wfDeLKYgDsdVBH5hKI_CUO_n0OoDU9Zs,7867
+gitroster-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+gitroster-0.2.0.dist-info/entry_points.txt,sha256=H2DSfJdK7RuGCnaPWnjgQj6-LTadTzh0EQn3ScOX44M,49
+gitroster-0.2.0.dist-info/top_level.txt,sha256=vMWHHsRpxmWDzirxSTp6O56ifb1_NpRerm51q3NBEN4,10
+gitroster-0.2.0.dist-info/RECORD,,

gitroster-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gitroster-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitroster = gitroster.cli:main

gitroster-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 gitroster contributors
+
+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.

gitroster-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gitroster