gitroster 0.2.0__py3-none-any.whl

gitroster/__init__.py

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

gitroster/__main__.py

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

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/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/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

gitroster/deps.py

@@ -0,0 +1,207 @@
+"""Read dependency manifests (npm, PyPI, Go, Cargo, Composer). Parsers are small and forgiving on purpose."""
+import json
+import os
+import re
+from pathlib import Path
+
+MAX_DEPS = 500
+PRUNE = {"node_modules", ".git", "__pycache__", "vendor", "dist", "build", "target", ".venv", "venv", "env"}
+REQ_RE = re.compile(r"^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[[^\]]*\])?\s*([^;#]*)")
+STR_RE = re.compile(r"""["']([^"']+)["']""")
+
+
+def _read(path):
+    try:
+        return Path(path).read_text(encoding="utf-8", errors="replace")[:400000]
+    except OSError:
+        return ""
+
+
+def _norm_py(name):
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def _req(line):
+    m = REQ_RE.match(line.strip())
+    return (_norm_py(m.group(1)), m.group(2).strip()) if m else None
+
+
+def _toml_sections(text):
+    sections, cur = {}, ""
+    for line in text.splitlines():
+        m = re.match(r"^\s*\[{1,2}([^\]]+)\]{1,2}\s*$", line)
+        if m:
+            cur = m.group(1).strip()
+            sections.setdefault(cur, [])
+        elif cur is not None:
+            sections.setdefault(cur, []).append(line)
+    return sections
+
+
+def _toml_value(v):
+    v = v.strip()
+    m = re.match(r"""^["']([^"']*)["']""", v)
+    if m:
+        return m.group(1)
+    m = re.search(r"""version\s*=\s*["']([^"']*)["']""", v)
+    return m.group(1) if m else "*"
+
+
+def _toml_table_deps(lines, eco, dev, skip=()):
+    out = []
+    for line in lines:
+        m = re.match(r"""^\s*["']?([A-Za-z0-9_.-]+)["']?\s*=\s*(.+)$""", line)
+        if m and m.group(1) not in skip:
+            out.append({"name": _norm_py(m.group(1)) if eco == "pypi" else m.group(1), "spec": _toml_value(m.group(2)), "eco": eco, "dev": dev})
+    return out
+
+
+def _toml_array(lines, key):
+    """Strings of `key = [ ... ]` (one or many lines)."""
+    out, collecting = [], False
+    for line in lines:
+        if not collecting:
+            m = re.match(rf"^\s*{re.escape(key)}\s*=\s*\[(.*)$", line)
+            if not m:
+                continue
+            collecting, line = True, m.group(1)
+        out += STR_RE.findall(line)
+        if "]" in re.sub(r"\"[^\"]*\"|'[^']*'", "", line):  # a `]` outside quotes closes the array
+            collecting = False
+    return out
+
+
+def pyproject(text):
+    sec = _toml_sections(text)
+    name, deps = "", []
+    project = sec.get("project", [])
+    for line in project:
+        m = re.match(r"""^\s*name\s*=\s*["']([^"']+)["']""", line)
+        if m:
+            name = _norm_py(m.group(1))
+    for s in _toml_array(project, "dependencies"):
+        r = _req(s)
+        if r:
+            deps.append({"name": r[0], "spec": r[1], "eco": "pypi", "dev": False})
+    optional = sec.get("project.optional-dependencies", [])
+    for group in re.findall(r"^\s*([\w-]+)\s*=\s*\[", "\n".join(optional), re.M):
+        for s_ in _toml_array(optional, group):
+            r = _req(s_)
+            if r:
+                deps.append({"name": r[0], "spec": r[1], "eco": "pypi", "dev": True})
+    if "tool.poetry" in sec and not name:
+        for line in sec["tool.poetry"]:
+            m = re.match(r"""^\s*name\s*=\s*["']([^"']+)["']""", line)
+            if m:
+                name = _norm_py(m.group(1))
+    deps += _toml_table_deps(sec.get("tool.poetry.dependencies", []), "pypi", False, skip=("python",))
+    for key in ("tool.poetry.dev-dependencies", "tool.poetry.group.dev.dependencies"):
+        deps += _toml_table_deps(sec.get(key, []), "pypi", True)
+    return name, deps
+
+
+def requirements(text):
+    out = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith(("#", "-", "git+", "http")):
+            continue
+        r = _req(line)
+        if r:
+            out.append({"name": r[0], "spec": r[1], "eco": "pypi", "dev": False})
+    return out
+
+
+def package_json(text):
+    try:
+        data = json.loads(text)
+    except ValueError:
+        return "", []
+    if not isinstance(data, dict):
+        return "", []
+    out = []
+    for key, dev in (("dependencies", False), ("devDependencies", True)):
+        for k, v in (data.get(key) or {}).items():
+            out.append({"name": k, "spec": str(v), "eco": "npm", "dev": dev})
+    return str(data.get("name") or ""), out
+
+
+def composer_json(text):
+    try:
+        data = json.loads(text)
+    except ValueError:
+        return "", []
+    if not isinstance(data, dict):
+        return "", []
+    out = []
+    for key, dev in (("require", False), ("require-dev", True)):
+        for k, v in (data.get(key) or {}).items():
+            if "/" in k:
+                out.append({"name": k, "spec": str(v), "eco": "composer", "dev": dev})
+    return str(data.get("name") or ""), out
+
+
+def go_mod(text):
+    name, out, block = "", [], False
+    for line in text.splitlines():
+        line = line.split("//")[0].strip()
+        m = re.match(r"^module\s+(\S+)", line)
+        if m:
+            name = m.group(1)
+        elif re.match(r"^require\s*\($", line):
+            block = True
+        elif block and line == ")":
+            block = False
+        else:
+            m = re.match(r"^(?:require\s+)?(\S+)\s+(v\S+)$", line) if (block or line.startswith("require ")) else None
+            if m:
+                out.append({"name": m.group(1), "spec": m.group(2), "eco": "go", "dev": False})
+    return name, out
+
+
+def cargo(text):
+    sec = _toml_sections(text)
+    name = ""
+    for line in sec.get("package", []):
+        m = re.match(r"""^\s*name\s*=\s*["']([^"']+)["']""", line)
+        if m:
+            name = m.group(1)
+    out = _toml_table_deps(sec.get("dependencies", []), "cargo", False)
+    out += _toml_table_deps(sec.get("dev-dependencies", []), "cargo", True)
+    out += _toml_table_deps(sec.get("build-dependencies", []), "cargo", True)
+    return name, out
+
+
+def _manifests(d):
+    """(names, deps) for one folder."""
+    names, deps = [], []
+    for fname, fn, eco in (("package.json", package_json, "npm"), ("composer.json", composer_json, "composer"),
+                           ("go.mod", go_mod, "go"), ("Cargo.toml", cargo, "cargo"), ("pyproject.toml", pyproject, "pypi")):
+        text = _read(d / fname)
+        if text:
+            n, dd = fn(text)
+            if n:
+                names.append({"eco": eco, "name": n})
+            deps += dd
+    seen = {(x["name"]) for x in deps if x["eco"] == "pypi"}
+    for f in sorted(d.glob("requirements*.txt"))[:4]:
+        dev = "dev" in f.name or "test" in f.name
+        for x in requirements(_read(f)):
+            if x["name"] not in seen:
+                seen.add(x["name"])
+                x["dev"] = dev
+                deps.append(x)
+    return names, deps
+
+
+def collect(path):
+    """Dependencies of a repo: its root and immediate subfolders that have a manifest."""
+    root = Path(path)
+    names, deps = _manifests(root)
+    for d in sorted(p for p in root.iterdir() if p.is_dir() and p.name not in PRUNE and not p.name.startswith(".")) if root.is_dir() else []:
+        n, dd = _manifests(d)
+        names += n
+        for x in dd:
+            x["where"] = d.name
+        deps += dd
+    return {"names": names, "deps": deps[:MAX_DEPS]}

gitroster/export.py

@@ -0,0 +1,40 @@
+"""Markdown export of the whole inventory."""
+import time
+
+
+def _home(p):
+    import os
+    h = os.path.expanduser("~")
+    return "~" + p[len(h):] if p.startswith(h) else p
+
+
+def markdown(scan, meta):
+    repos = [r for r in scan.get("repos", []) if not meta.get(r["path"], {}).get("ignored")]
+    out = [f"# Repo inventory", "", f"{len(repos)} repos, scanned {time.strftime('%Y-%m-%d %H:%M', time.localtime(scan.get('scanned', time.time())))}", ""]
+    for r in repos:
+        m = meta.get(r["path"], {})
+        out += [f"## {r['name']}", "",
+                f"- path: `{_home(r['path'])}`",
+                f"- kind: {r['kind']}" + (f" · remote: {r['remote']}" if r.get("remote") else ""),
+                f"- stack: {', '.join(r['stack']) or '-'}"]
+        if r.get("summary"):
+            out.append(f"- about: {r['summary']}")
+        if m.get("note"):
+            out.append(f"- note: {m['note']}")
+        if r.get("setup"):
+            out.append("- setup: " + "; ".join(f"`{c}`" for c in r["setup"]))
+        if r.get("run"):
+            out.append("- run: " + "; ".join(f"`{c}`" for c in r["run"]))
+        if r.get("ports"):
+            out.append("- ports: " + ", ".join(str(p) for p in r["ports"]))
+        w = r.get("work") or {}
+        if w.get("stashes"):
+            out.append(f"- stashes: {len(w['stashes'])}")
+        for b in w.get("branches", []):
+            out.append(f"- branch `{b['name']}`: {b['state']}" + (f" (ahead {b['ahead']})" if b["ahead"] else ""))
+        for t in w.get("worktrees", []):
+            out.append(f"- worktree `{t['path']}` ({t['branch'] or 'detached'})" + (" MISSING" if t["missing"] else ""))
+        for h in r.get("health", []):
+            out.append(f"- WARNING: {h['text']}" + (f" ({', '.join(h['files'])})" if h["files"] else ""))
+        out.append("")
+    return "\n".join(out)