gitroster 0.2.0__tar.gz

gitroster-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,113 @@
+<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/gitroster/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

gitroster-0.2.0/gitroster/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+import sys
+
+sys.exit(main())

gitroster-0.2.0/gitroster/agent.py

@@ -0,0 +1,157 @@
+"""Optional: ask a coding agent CLI you already have to summarize a repo.
+
+Nothing here talks to a network service itself and no API keys are handled. gitroster only runs the
+agent CLI you chose, feeds it a prompt on stdin and asks it not to use tools. The answer is stored
+as "AI-generated, unverified".
+"""
+import json
+import os
+import re
+import shlex
+import subprocess
+import time
+from pathlib import Path
+
+from . import scanner
+from .pathscan import which
+
+# id, label, program, arguments, how to install. The prompt is written to stdin. Every entry must keep
+# the agent away from tools: the summary needs only text, and nothing should be run or edited.
+AGENTS = [
+    ("claude", "Claude Code", "claude", ["-p", "--disallowedTools", "Bash,Edit,Write,NotebookEdit"],
+     "npm install -g @anthropic-ai/claude-code"),
+    ("codex", "Codex CLI", "codex", ["exec", "--sandbox", "read-only", "--skip-git-repo-check", "-"],
+     "npm install -g @openai/codex"),
+    ("gemini", "Gemini CLI", "gemini", ["-p", "Follow the instructions in the input exactly. Do not use tools."],
+     "npm install -g @google/gemini-cli"),
+]
+
+PROMPT = """You are helping a developer remember a project they wrote or cloned long ago.
+Use ONLY the facts below. If something is not in the facts, say "unknown". Do not run commands or use tools.
+
+Answer with ONLY a JSON object (no markdown fence) with these string keys:
+  "what":   one sentence on what this project is and does
+  "stack":  the main languages, frameworks and services, short
+  "run":    how to set it up and start it, 1-3 short steps, or "unknown"
+  "status": what the recent commits, unmerged branches and stashes suggest was being worked on, 1-2 sentences
+  "watch":  gotchas such as API keys, GPUs, databases, large downloads; "none" if nothing is apparent
+
+--- FACTS ---
+Name: {name}
+Path: {path}
+Kind: {kind}   Branch: {branch}   Uncommitted changes: {dirty}   Unpushed commits: {ahead}
+Detected stack: {stack}
+Setup commands: {setup}
+Run commands: {run}
+Dependencies: {deps}
+Local-only or unmerged branches: {branches}
+Stashes: {stashes}
+
+Recent commits (newest first):
+{commits}
+
+File tree (depth 2):
+{tree}
+
+README (truncated):
+{readme}
+"""
+
+
+def detect():
+    """Agent CLIs installed on this machine."""
+    return [{"id": e[0], "label": e[1]} for e in AGENTS if which(e[2])]
+
+
+def catalog():
+    """Every agent gitroster knows how to drive, with whether it is installed here."""
+    return [{"id": i, "label": label, "installed": bool(which(prog)), "install": hint} for i, label, prog, _, hint in AGENTS]
+
+
+def _resolve(argv):
+    return [which(argv[0]) or argv[0], *argv[1:]]
+
+
+def command(settings=None, override=None):
+    """-> (argv, label). Precedence: --agent-cmd / $GITROSTER_AGENT, a custom command from Settings,
+    the agent picked in Settings, then the first one found."""
+    explicit = override or os.environ.get("GITROSTER_AGENT")
+    if explicit:
+        return _resolve(shlex.split(explicit)), "custom command"
+    settings = settings or {}
+    if settings.get("agent") == "custom" and settings.get("agent_custom"):
+        return _resolve(shlex.split(settings["agent_custom"])), "custom command"
+    entries = [e for e in AGENTS if which(e[2])]
+    chosen = next((e for e in entries if e[0] == settings.get("agent")), entries[0] if entries else None)
+    if not chosen:
+        return None, ""
+    return [which(chosen[2]), *chosen[3]], chosen[1]
+
+
+def tree(path, depth=2, limit=80):
+    root = Path(path)
+    out = []
+    for dirpath, dirs, files in os.walk(root):
+        rel = Path(dirpath).relative_to(root)
+        if len(rel.parts) >= depth:
+            dirs[:] = []
+        dirs[:] = sorted(d for d in dirs if d not in (".git", "node_modules", "__pycache__") and not d.startswith(".venv"))
+        for name in sorted(files)[:15]:
+            shown = str(rel / name) if rel.parts else name
+            if not scanner.SECRET_FILES.search(shown):  # never even list secret-looking files
+                out.append(shown)
+        if len(out) >= limit:
+            break
+    return "\n".join(out[:limit])
+
+
+def build_prompt(repo):
+    p = Path(repo["path"])
+    text = ""
+    for n in ("README.md", "readme.md", "README.rst", "README.txt"):
+        if (p / n).exists():
+            text = (p / n).read_text(errors="replace")[:6000]
+            break
+    w = repo.get("work") or {}
+    commits = "\n".join(f"- {c['subject']}" for c in scanner.graph(p, 15)) or "none"
+    deps = ", ".join(d["name"] for d in repo.get("deps", [])[:25]) or "none"
+    return PROMPT.format(
+        name=repo["name"], path=repo["path"], kind=repo.get("kind", ""), branch=repo.get("branch", ""),
+        dirty="yes" if repo.get("dirty") else "no", ahead=repo.get("ahead", 0),
+        stack=", ".join(repo["stack"]) or "unknown", setup="; ".join(repo["setup"]) or "none",
+        run="; ".join(repo["run"]) or "none", deps=deps,
+        branches=", ".join(f"{b['name']} ({b['state']})" for b in w.get("branches", [])[:8]) or "none",
+        stashes="; ".join(s["message"] for s in w.get("stashes", [])[:5]) or "none",
+        commits=commits, tree=tree(p), readme=text or "(no README)")
+
+
+KEYS = ("what", "stack", "run", "status", "watch")
+
+
+def parse(text):
+    """The agent's answer as {what, stack, run, status, watch}; falls back to the raw text."""
+    cleaned = re.sub(r"^```(?:json)?\s*|\s*```$", "", text.strip())
+    for candidate in (cleaned, cleaned[cleaned.find("{"):cleaned.rfind("}") + 1]):
+        try:
+            data = json.loads(candidate)
+        except ValueError:
+            continue
+        if isinstance(data, dict) and any(k in data for k in KEYS):
+            return {k: str(data.get(k, "")).strip()[:600] for k in KEYS}
+    return {"raw": text.strip()[:2000]}
+
+
+def summarize(repo, settings=None, override=None, timeout=180):
+    argv, label = command(settings, override)
+    if not argv:
+        raise RuntimeError("no agent CLI found; install Claude Code, Codex or Gemini CLI, or set a custom command in Settings")
+    try:
+        r = subprocess.run(argv, input=build_prompt(repo), capture_output=True, text=True, encoding="utf-8",
+                           errors="replace", timeout=timeout, cwd=repo["path"])
+    except FileNotFoundError:
+        raise RuntimeError(f"agent command not found: {argv[0]}")
+    except subprocess.TimeoutExpired:
+        raise RuntimeError("the agent took too long")
+    if r.returncode != 0 or not r.stdout.strip():
+        raise RuntimeError((r.stderr or "the agent returned nothing").strip()[:300])
+    return {**parse(r.stdout), "agent": label, "head": repo.get("head", ""), "at": time.time()}

gitroster-0.2.0/gitroster/cli.py

@@ -0,0 +1,43 @@
+import argparse
+import json
+import sys
+import webbrowser
+from pathlib import Path
+
+from . import __version__, demo, scanner
+from .server import App, serve
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="gitroster",
+                                 description="Find the repos, envs and ports you forgot about.")
+    ap.add_argument("roots", nargs="*", default=[str(Path.home())], help="folders to scan (default: ~)")
+    ap.add_argument("--port", type=int, default=8765)
+    ap.add_argument("--json", action="store_true", help="print one scan as JSON and exit")
+    ap.add_argument("--open", action="store_true", help="open the page in a browser")
+    ap.add_argument("--agent-cmd", help='command for AI summaries; reads the prompt on stdin '
+                                        '(default: "claude -p", or $GITROSTER_AGENT)')
+    ap.add_argument("--demo", action="store_true", help="show sample repos instead of scanning your machine")
+    ap.add_argument("--version", action="version", version=f"gitroster {__version__}")
+    a = ap.parse_args(argv)
+
+    if a.json:
+        json.dump(scanner.scan(a.roots), sys.stdout, indent=2)
+        return 0
+
+    if a.demo:
+        roots, store = demo.setup()
+        app = App(roots, a.port, store=store, agent_cmd=a.agent_cmd, demo=True)
+        a.roots = ["sample repos"]
+    else:
+        app = App(a.roots, a.port, agent_cmd=a.agent_cmd)
+    url = f"http://127.0.0.1:{a.port}"
+    print(f"gitroster {__version__} on {url}  (scanning {', '.join(a.roots)})")
+    if a.open:
+        webbrowser.open(url)
+    serve(app)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gitroster-0.2.0/gitroster/demo.py

@@ -0,0 +1,140 @@
+"""`gitroster --demo`: a throwaway set of sample repos, so the UI can be tried or photographed without
+scanning a real machine. Nothing here touches your own folders, settings or processes."""
+import atexit
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+from . import procs
+from .store import Store
+
+DAY = 86400
+ME = ("Demo User", "demo@example.com")
+
+# name, remote, files, [(days ago, message)], extra setup name
+REPOS = [
+    ("atlas-api", "https://github.com/demo-user/atlas-api.git", {
+        "README.md": "# Atlas API\n\nA small REST API that serves product data for the storefront.\n\n```bash\nnpm run dev\n```\n\nOpen http://localhost:3000\n",
+        "package.json": '{"name":"atlas-api","scripts":{"dev":"node server.js","start":"node server.js"},"dependencies":{"express":"^4.19.0","zod":"^3.23.0"}}',
+        ".gitignore": "node_modules\n.env\n",
+        "server.js": "require('express')().listen(3000)\n"},
+     [(40, "Add product schema"), (9, "Validate query params"), (2, "Cache product list")], "ahead"),
+    ("bookshelf", "https://github.com/demo-user/bookshelf.git", {
+        "README.md": "# Bookshelf\n\nTrack the books you read and what you thought of them.\n",
+        "requirements.txt": "flask==3.0.3\nsqlalchemy==2.0.30\n",
+        "app.py": "print('bookshelf')\n",
+        ".gitignore": ".venv\n"},
+     [(120, "First version"), (30, "Add ratings"), (5, "Import from CSV")], "work"),
+    ("dashboard-ui", "https://github.com/demo-user/dashboard-ui.git", {
+        "README.md": "# Dashboard UI\n\nFront end for the Atlas API, built with Vite.\n\nRuns on http://localhost:5173\n",
+        "package.json": '{"name":"dashboard-ui","scripts":{"dev":"vite"},"dependencies":{"vite":"^5.2.0","zod":"^3.22.0"}}',
+        ".gitignore": "node_modules\n"},
+     [(60, "Scaffold with Vite"), (3, "Add chart panel")], None),
+    ("rust-notes", "https://github.com/someone/rust-notes.git", {
+        "README.md": "# rust-notes\n\nA command line notebook written in Rust.\n",
+        "Cargo.toml": '[package]\nname = "rust-notes"\nversion = "0.3.0"\n\n[dependencies]\nclap = "4"\n',
+        ".gitignore": "target\n"},
+     [(300, "Release 0.3.0")], "clone"),
+    ("weather-cli", "https://github.com/demo-user/weather-cli.git", {
+        "README.md": "# weather-cli\n\nPrints the weather forecast in your terminal. Forked to add metric units.\n",
+        "go.mod": "module example.com/weather\n\ngo 1.22\n",
+        "main.go": "package main\nfunc main() {}\n"},
+     [(210, "Fork upstream"), (190, "Add metric units")], "fork"),
+    ("old-experiment", None, {
+        "README.md": "# old experiment\n\nSomething I tried with a camera feed and never finished.\n",
+        "main.py": "print('todo')\n",
+        "requirements.txt": "opencv-python\n",
+        ".env": "CAMERA_KEY=demo\n"},
+     [(480, "wip"), (470, "wip 2")], "dirty"),
+]
+
+SUMMARIES = {
+    "atlas-api": {
+        "what": "REST API that serves product data to the storefront.",
+        "stack": "Node.js, Express, Zod",
+        "run": "npm run dev, then open http://localhost:3000",
+        "status": "Active. The last work added caching for the product list.",
+        "watch": "Two commits are not pushed yet.",
+    },
+    "bookshelf": {
+        "what": "Small web app to track the books you read, with ratings and CSV import.",
+        "stack": "Python, Flask, SQLAlchemy",
+        "run": "python3 -m venv .venv, install requirements.txt, then python3 app.py",
+        "status": "Was working on CSV import: there are uncommitted changes and a stash.",
+        "watch": "Check the stash before starting something new.",
+    },
+}
+
+NOTES = {"bookshelf": "Finish the CSV import, then deploy to the home server."}
+
+PORTS = [("atlas-api", 3000, "node server.js", "node"), ("dashboard-ui", 5173, "node node_modules/.bin/vite", "node")]
+
+
+def _git(path, *args, when=None):
+    env = {**os.environ, "GIT_AUTHOR_NAME": ME[0], "GIT_AUTHOR_EMAIL": ME[1],
+           "GIT_COMMITTER_NAME": ME[0], "GIT_COMMITTER_EMAIL": ME[1]}
+    if when:
+        env["GIT_AUTHOR_DATE"] = env["GIT_COMMITTER_DATE"] = f"{int(when)} +0000"
+    subprocess.run(["git", "-C", str(path), "-c", "commit.gpgsign=false", *args], env=env, check=True, capture_output=True)
+
+
+def _build(root, name, remote, files, commits, extra):
+    p = Path(root) / name
+    p.mkdir(parents=True)
+    _git(p, "init", "-q", "-b", "main")
+    _git(p, "config", "user.email", ME[1])
+    _git(p, "config", "user.name", ME[0])
+    for f, content in files.items():
+        (p / f).write_text(content)
+    now = time.time()
+    for i, (days, msg) in enumerate(commits):
+        (p / "CHANGELOG.txt").write_text("\n".join(m for _, m in commits[: i + 1]) + "\n")
+        _git(p, "add", "-A", "-f")
+        _git(p, "commit", "-q", "-m", msg, when=now - days * DAY)
+    if remote:
+        _git(p, "remote", "add", "origin", remote)
+        if extra == "clone":  # the commits are not yours: your configured email no longer matches the author
+            _git(p, "config", "user.email", "me@example.org")
+        if extra == "fork":
+            _git(p, "remote", "add", "upstream", "https://github.com/original/weather-cli.git")
+        _git(p, "update-ref", "refs/remotes/origin/main", "HEAD~2" if extra == "ahead" else "HEAD")
+        _git(p, "config", "branch.main.remote", "origin")
+        _git(p, "config", "branch.main.merge", "refs/heads/main")
+    if extra == "work":
+        _git(p, "checkout", "-q", "-b", "csv-import")
+        (p / "importer.py").write_text("def load(path):\n    pass\n")
+        _git(p, "add", "-A")
+        _git(p, "commit", "-q", "-m", "Start CSV importer", when=now - 5 * DAY)
+        _git(p, "checkout", "-q", "main")
+        (p / "scratch.py").write_text("print('try')\n")
+        _git(p, "add", "-A")
+        _git(p, "stash", "-q")
+        (p / "app.py").write_text("print('bookshelf, edited')\n")
+    if extra == "dirty":
+        (p / "main.py").write_text("print('half done')\n")
+    return p
+
+
+def setup():
+    """Create the sample repos, fake the port list, and return (roots, store)."""
+    base = Path(tempfile.mkdtemp(prefix="gitroster-demo-")).resolve()
+    atexit.register(shutil.rmtree, base, ignore_errors=True)
+    root = base / "projects"
+    paths = {}
+    for name, remote, files, commits, extra in REPOS:
+        paths[name] = _build(root, name, remote, files, commits, extra)
+    store = Store(base / "config", base / "state")  # state.parent is `base`, which the page shows as ~
+    for name, summary in SUMMARIES.items():
+        head = subprocess.run(["git", "-C", str(paths[name]), "rev-parse", "HEAD"], capture_output=True, text=True).stdout.strip()
+        store.update_meta(str(paths[name].resolve()), summary={**summary, "agent": "Demo", "head": head, "at": time.time() - 3600})
+    for name, note in NOTES.items():
+        store.update_meta(str(paths[name].resolve()), note=note)
+    store.update_meta(str(paths["atlas-api"].resolve()), pinned=True)
+    ports = [dict(procs._entry(port, "127.0.0.1", 40000 + i, proc, cmd, str(paths[name].resolve()), time.time() - 7200))
+             for i, (name, port, cmd, proc) in enumerate(PORTS)]
+    procs.listening = lambda: [dict(p) for p in ports]  # never read the real machine's ports
+    procs.docker_containers = lambda: []
+    return [str(root)], store