github-stars-organizer 0.2.0__py3-none-any.whl

github_stars_organizer-0.2.0.dist-info/METADATA

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: github-stars-organizer
+Version: 0.2.0
+Summary: Organize GitHub starred repos into Star Lists — free heuristic categorization, optional LLM
+Project-URL: Homepage, https://github.com/nishal21/github-stars-organizer
+Project-URL: Repository, https://github.com/nishal21/github-stars-organizer
+Project-URL: Issues, https://github.com/nishal21/github-stars-organizer/issues
+Author-email: Nishal K <nishal21@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,developer-tools,github,organize,productivity,stars
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Provides-Extra: llm
+Requires-Dist: openai>=1.0; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# GitHub Stars Organizer
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/nishal21/github-stars-organizer/actions/workflows/ci.yml/badge.svg)](https://github.com/nishal21/github-stars-organizer/actions/workflows/ci.yml)
+
+**Organize 300+ GitHub stars into lists in minutes — free, no AI required.**
+
+GitHub's official API can star/unstar repos, but **cannot create or manage Star Lists**. This CLI:
+
+1. Fetches your starred repos (public GitHub API)
+2. Categorizes them by name, description, language, and topics
+3. Creates lists and assigns repos via your browser session
+
+### Why this tool?
+
+| Tool | Drawback | This project |
+|------|----------|--------------|
+| [github-star-organizer](https://github.com/luoling8192/github-star-organizer) | Requires paid LLM API | **Free heuristic by default** |
+| [ghstars](https://github.com/snowfluke/github-manage-stars-unofficial) | Manual category files only | **Auto-plan + custom rules + optional LLM** |
+| [starred](https://github.com/amirhmoradi/starred) | AI-first, complex | **Simple: plan → review → apply** |
+
+## Install
+
+```bash
+# From source
+git clone https://github.com/nishal21/github-stars-organizer.git
+cd github-stars-organizer
+uv sync
+
+# Or from PyPI (after v0.2.0 release)
+pip install github-stars-organizer
+```
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/) (recommended).
+
+## Quick start
+
+### 1. Build a plan (no credentials needed)
+
+```bash
+organize-stars plan --username YOUR_USERNAME
+```
+
+Review `categorization-plan.json`. Edit assignments or add custom rules:
+
+```bash
+cp categories.example.toml categories.toml
+# edit categories.toml
+organize-stars plan --username YOUR_USERNAME --categories categories.toml
+```
+
+### 2. Configure credentials
+
+```bash
+organize-stars init
+```
+
+Or copy and edit manually:
+
+```bash
+cp config.example.toml config.toml
+```
+
+| Field | How to get it |
+|-------|----------------|
+| `username` | Your GitHub username |
+| `token` | [GitHub token settings](https://github.com/settings/tokens) (classic; `public_repo` if you star private repos) |
+| `cookies` | See [Getting your cookie](#getting-your-browser-cookie) below |
+
+### 3. Preview and apply
+
+```bash
+organize-stars apply --dry-run
+organize-stars apply
+```
+
+View result: `https://github.com/YOUR_USERNAME?tab=stars`
+
+If interrupted, resume with:
+
+```bash
+organize-stars apply --resume
+```
+
+## Getting your browser cookie
+
+GitHub Star Lists have no public API — applying lists uses your browser session.
+
+1. Log into [github.com](https://github.com) in Chrome or Edge
+2. Press **F12** to open DevTools
+3. Open the **Network** tab
+4. Refresh the page
+5. Click any request to `github.com`
+6. Under **Headers**, find **Cookie**
+7. Copy the **entire** cookie string into `config.toml` → `[github.session]` → `cookies`
+
+Cookies expire every few weeks. Refresh from DevTools if you get CSRF or 403 errors.
+
+## CLI reference
+
+```bash
+organize-stars init [--config config.toml] [--force]
+organize-stars status [--config config.toml]
+organize-stars lists [--config config.toml]
+
+organize-stars plan --username USER [--categories categories.toml] [--output plan.json]
+organize-stars plan --config config.toml [--categories categories.toml]
+organize-stars plan --config config.toml --llm          # optional AI mode
+
+organize-stars apply [--config config.toml] [--plan plan.json] [--dry-run] [--yes] [--resume]
+```
+
+## Optional LLM mode
+
+For smarter categorization, add a `[llm]` section to `config.toml` and install the extra:
+
+```bash
+uv sync --extra llm
+organize-stars plan --config config.toml --llm
+```
+
+Heuristic mode remains the default — no API key required.
+
+## Default categories
+
+- AI & LLM
+- Web Dev & Frontend
+- Mobile & Android
+- Backend & APIs
+- Dev Tools & CLI
+- Self-hosting & DevOps
+- Security & Privacy
+- Media & Creative
+- Gaming & Entertainment
+- Go & Systems
+- Learning & Inspiration
+- Misc & Tools
+
+Customize via `categories.toml` or edit the plan JSON before applying.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| CSRF / 403 error | Refresh browser cookie in `config.toml` |
+| Rate limited | Wait a few minutes; reduce `concurrency` in config |
+| More than 32 lists | GitHub hard limit — merge categories in plan or `categories.toml` |
+| Apply interrupted | Run `organize-stars apply --resume` |
+| `config.toml not found` | Run `organize-stars init` |
+
+Check setup anytime:
+
+```bash
+organize-stars status
+```
+
+## Privacy and security
+
+- Token and cookies stay in local `config.toml` (gitignored) — never commit them
+- Plan mode reads only **public** repo metadata
+- LLM mode (optional) sends metadata to your configured provider
+- See [SECURITY.md](SECURITY.md)
+
+## Development
+
+```bash
+uv sync --dev
+uv run pytest
+uv run ruff check .
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Attribution
+
+Web client adapted from [luoling8192/github-star-organizer](https://github.com/luoling8192/github-star-organizer) (MIT). See [ATTRIBUTION.md](ATTRIBUTION.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

github_stars_organizer-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+stars_organizer/__init__.py,sha256=Mrp2_JPrfHQk8JfYLYSYPIS2M_Eo732pz1T7uwhsho8,83
+stars_organizer/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+stars_organizer/apply.py,sha256=6VMLRzMvV1gK5iizXSn8sk1H2OUlXm8dU3bSrbTOQAc,5547
+stars_organizer/categorize.py,sha256=vyLIf7I5Bv6gSu24FH3_2dQWrQhk2Gl10OQprgtBC3k,6472
+stars_organizer/cli.py,sha256=cLq3hbxlb5SYeDo-h23vUhhpWNTv1zeTncskB7kSev0,7835
+stars_organizer/config.py,sha256=k3WWFz1W8fM3fLb8hAxiik0-Z-NbUt57jRgYNzeqtUs,1992
+stars_organizer/github_api.py,sha256=sifiqceMThG71hTcEPYki9oG6XcKKpY-qx7NZJsgWfk,2292
+stars_organizer/github_web.py,sha256=PRSsjbCau9C9pYMQsj-xXlP_ZzoRgL7jYKVTHUny7j8,11469
+stars_organizer/llm_categorize.py,sha256=0pV1xWiOIhpMUs7yNukJNvrh4blPYRrK54qjVtQUKXI,4588
+stars_organizer/models.py,sha256=r6rBucH1UCcZaGnkblaRHv4gTxsT3EE3PGHJI5x8T1Y,988
+stars_organizer/state.py,sha256=ELUWY_rM9DCYrLxodpTfdnYnhCtTooykx-NbyyJNzoc,972
+github_stars_organizer-0.2.0.dist-info/METADATA,sha256=z4FC4WOj---MsFsbKLkAFux6419BQeIDw9AtNSnnEZo,6374
+github_stars_organizer-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+github_stars_organizer-0.2.0.dist-info/entry_points.txt,sha256=mPiRXiwLnXQsW-SKLfgXu1xDNG4x4iR-qzoHmKln-Iw,60
+github_stars_organizer-0.2.0.dist-info/licenses/LICENSE,sha256=gIc-_Nua6iVpPBPg8sjkcLzk0suICMIpdA0OzdfmViA,1065
+github_stars_organizer-0.2.0.dist-info/RECORD,,

github_stars_organizer-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

github_stars_organizer-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+organize-stars = stars_organizer.cli:main

github_stars_organizer-0.2.0.dist-info/licenses/LICENSE

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

stars_organizer/__init__.py

@@ -0,0 +1,3 @@
+"""Organize GitHub starred repositories into Star Lists."""
+
+__version__ = "0.1.0"

stars_organizer/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

stars_organizer/apply.py

@@ -0,0 +1,155 @@
+"""Apply a categorization plan to GitHub Star Lists."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+
+from rich.console import Console
+from rich.progress import BarColumn, Progress, SpinnerColumn, TaskProgressColumn, TextColumn
+
+from .categorize import MAX_LISTS, load_plan
+from .config import load_config
+from .github_api import fetch_starred_repos
+from .github_web import GitHubWebClient
+from .models import Assignment, CategorizationResult
+from .state import DEFAULT_STATE_PATH, ApplyState
+
+console = Console()
+
+
+async def apply_plan(
+    *,
+    dry_run: bool,
+    config_path: Path,
+    plan_path: Path,
+    yes: bool = False,
+    resume: bool = False,
+    state_path: Path = DEFAULT_STATE_PATH,
+) -> None:
+    cfg = load_config(config_path)
+    assignments_map = load_plan(plan_path)
+
+    console.print(f"Loaded plan: {len(assignments_map)} repos")
+    repos = await fetch_starred_repos(cfg.github)
+    if not repos:
+        console.print("[red]No starred repos found. Check your GitHub token in config.toml.[/red]")
+        return
+
+    repo_by_name = {r.full_name: r for r in repos}
+    missing = [name for name in assignments_map if name not in repo_by_name]
+    if missing:
+        console.print(
+            f"[yellow]Warning: {len(missing)} repos no longer starred (skipped).[/yellow]"
+        )
+
+    assignments = [
+        Assignment(repo=name, list_name=list_name)
+        for name, list_name in assignments_map.items()
+        if name in repo_by_name
+    ]
+
+    by_list: dict[str, list[str]] = defaultdict(list)
+    for assignment in assignments:
+        by_list[assignment.list_name].append(assignment.repo)
+
+    console.print("\nPlanned lists:")
+    for list_name in sorted(by_list, key=lambda key: (-len(by_list[key]), key)):
+        console.print(f"  {list_name}: {len(by_list[list_name])} repos")
+
+    if len(by_list) > MAX_LISTS:
+        console.print(
+            f"\n[red]Error: plan has {len(by_list)} lists; GitHub max is {MAX_LISTS}.[/red]"
+            " Merge categories before applying."
+        )
+        return
+
+    if dry_run:
+        console.print("\n[yellow]Dry run — no changes applied.[/yellow]")
+        return
+
+    if not yes:
+        confirm = console.input(
+            "\n[bold]Apply these lists to GitHub? (y/N): [/bold]"
+        ).strip().lower()
+        if confirm != "y":
+            console.print("Aborted.")
+            return
+
+    state = ApplyState.load(state_path) if resume else None
+    if state and state.plan_path != str(plan_path.resolve()):
+        console.print("[yellow]Resume state is for a different plan; starting fresh.[/yellow]")
+        state = None
+
+    if state is None:
+        state = ApplyState(plan_path=str(plan_path.resolve()))
+
+    already_assigned = set(state.assigned_repos)
+    pending = [a for a in assignments if a.repo not in already_assigned]
+
+    result = CategorizationResult(
+        assignments=pending,
+        new_lists=sorted(name for name in by_list if name not in state.lists_created),
+    )
+
+    web = GitHubWebClient(cfg.github)
+    try:
+        existing_lists = await web.get_lists(repos[0])
+        list_name_to_id = {item.name: item.id for item in existing_lists}
+        for name in state.lists_created:
+            for item in existing_lists:
+                if item.name == name:
+                    list_name_to_id[item.name] = item.id
+
+        if result.new_lists:
+            console.print(f"\nCreating {len(result.new_lists)} lists...")
+            for name in result.new_lists:
+                if name in list_name_to_id:
+                    continue
+                created = await web.create_list(name, repos[0])
+                if created:
+                    list_name_to_id[created.name] = created.id
+                    state.lists_created.append(created.name)
+                    state.save(state_path)
+                    console.print(f"  [green]+[/green] {name}")
+                else:
+                    console.print(f"  [red]![/red] Failed: {name}")
+
+        console.print(f"\nAssigning {len(pending)} repos...")
+        ok = len(already_assigned)
+
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TaskProgressColumn(),
+            console=console,
+        ) as progress:
+            task = progress.add_task("Assigning repos...", total=len(pending))
+            for assignment in pending:
+                repo = repo_by_name.get(assignment.repo)
+                target_id = list_name_to_id.get(assignment.list_name)
+                if not repo or not target_id:
+                    progress.advance(task)
+                    continue
+                if await web.assign_repo(repo, [target_id]):
+                    ok += 1
+                    state.assigned_repos.append(assignment.repo)
+                else:
+                    state.failed_repos.append(assignment.repo)
+                state.save(state_path)
+                progress.advance(task)
+
+        if state.failed_repos:
+            console.print(
+                f"\n[yellow]Done with {len(state.failed_repos)} failures. "
+                f"Re-run with --resume to retry.[/yellow]"
+            )
+        else:
+            ApplyState.clear(state_path)
+            console.print(
+                f"\n[bold green]Done![/bold green] Assigned {ok}/{len(assignments)} repos."
+            )
+        console.print(f"View: https://github.com/{cfg.github.username}?tab=stars")
+    finally:
+        await web.close()

stars_organizer/categorize.py

@@ -0,0 +1,177 @@
+"""Heuristic categorization of starred repositories into broad lists."""
+
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from collections import defaultdict
+from pathlib import Path
+
+from .models import StarredRepo
+
+CATEGORIES: dict[str, list[tuple[str, int]]] = {
+    "AI & LLM": [
+        (r"\b(llm|gpt|claude|openai|gemini|mistral|ollama|whisper|transformer|langchain|copilot|codex|inference|embedding|rag\b|fine-?tun|huggingface|pytorch|tensorflow|neural|speech|tts|text-to-speech|voice|skill\b|agent\b|mcp\b|synthid|deepseek|llama|anthropic)", 3),
+        (r"\b(ai\b|machine-learning|ml\b|computer-vision|nlp\b|generative)", 2),
+    ],
+    "Web Dev & Frontend": [
+        (r"\b(react|nextjs|next\.js|vue|svelte|tailwind|frontend|responsive|portfolio|css|html|ui\b|component|design-system|landing|website|web-app|browser|electron|vite|webpack|angular)", 3),
+        (r"\b(javascript|typescript|web\b|frontend|css-framework)", 1),
+    ],
+    "Mobile & Android": [
+        (r"\b(android|ios|flutter|dart|kotlin|swift|scrcpy|mobile|apk|iphone|ipad|react-native|expo)", 3),
+    ],
+    "Dev Tools & CLI": [
+        (r"\b(cli\b|terminal|vscode|cursor|git\b|github|developer-tool|devtools|automation|workflow|productivity|dotfiles|neovim|vim|shell|bash|zsh|toolkit|utility|script)", 2),
+        (r"\b(debug|lint|format|test|benchmark|monitor|log\b|trace)", 1),
+    ],
+    "Backend & APIs": [
+        (r"\b(api\b|backend|server|fastapi|express|graphql|rest\b|microservice|database|postgres|redis|mongodb|mysql|orm\b|grpc|websocket|auth\b|oauth|jwt)", 3),
+        (r"\b(node\b|django|flask|rails|laravel|spring)", 2),
+    ],
+    "Security & Privacy": [
+        (r"\b(security|privacy|vpn|proxy|encrypt|pentest|malware|reverse-engineer|exploit|vulnerability|firewall|tor\b|anonymous|hack\b|ctf\b|red-team|blue-team|atomic-red)", 3),
+    ],
+    "Media & Creative": [
+        (r"\b(video|audio|image|ffmpeg|media|edit|creative|photo|music|podcast|stream|youtube|animation|render|graphics|canvas|figma|design\b|art\b|tts|speech)", 2),
+    ],
+    "Self-hosting & DevOps": [
+        (r"\b(self-host|docker|kubernetes|k8s|homelab|raspberry|router|linux|infra|deploy|cloud|aws|azure|gcp|terraform|ansible|ci/cd|github-actions|nginx|proxy-server|serverless)", 3),
+        (r"\b(devops|infrastructure|container|helm|monitoring|grafana|prometheus)", 2),
+    ],
+    "Gaming & Entertainment": [
+        (r"\b(game|gaming|minecraft|steam|emulator|retro|unity|unreal|godot|anime|manga|otaku|dating-app)", 3),
+    ],
+    "Learning & Inspiration": [
+        (r"\b(tutorial|learn|course|awesome-|education|docs\b|guide|example|sample|template|starter|boilerplate|thesis|defense|portfolio|inspiration|list-of|curated|collection)", 2),
+    ],
+    "Go & Systems": [
+        (r"\b(go\b|golang|rust|systems|kernel|embedded|firmware|hardware|c\b|c\+\+|assembly|low-level|performance|memory|compiler)", 2),
+    ],
+}
+
+# Tie-breakers only when multiple categories score equally (not fallback defaults).
+LANG_HINTS = {
+    "typescript": "Web Dev & Frontend",
+    "javascript": "Web Dev & Frontend",
+    "go": "Go & Systems",
+    "rust": "Go & Systems",
+    "kotlin": "Mobile & Android",
+    "swift": "Mobile & Android",
+    "dart": "Mobile & Android",
+    "php": "Backend & APIs",
+    "ruby": "Backend & APIs",
+    "java": "Backend & APIs",
+}
+
+MAX_LISTS = 32
+
+DEFAULT_CATEGORY = "Misc & Tools"
+
+
+def load_categories(path: Path) -> dict[str, list[tuple[str, int]]]:
+    """Load custom category rules from a TOML file."""
+    with open(path, "rb") as f:
+        raw = tomllib.load(f)
+
+    categories: dict[str, list[tuple[str, int]]] = {}
+    for entry in raw.get("category", []):
+        name = entry["name"]
+        weight = int(entry.get("weight", 2))
+        patterns = entry.get("patterns", [])
+        # User patterns use substring match (e.g. "anime" matches "anime-api").
+        categories[name] = [(re.escape(pattern), weight) for pattern in patterns]
+    return categories
+
+
+def merge_categories(
+    custom: dict[str, list[tuple[str, int]]] | None = None,
+    *,
+    override: bool = False,
+) -> dict[str, list[tuple[str, int]]]:
+    """Merge custom categories with defaults. Custom rules are checked first."""
+    if not custom:
+        return dict(CATEGORIES)
+    if override:
+        return dict(custom)
+    merged = dict(CATEGORIES)
+    for name, patterns in custom.items():
+        merged[name] = patterns
+    return merged
+
+
+def _repo_text(repo: StarredRepo) -> str:
+    return " ".join(
+        filter(
+            None,
+            [
+                repo.full_name,
+                repo.description,
+                repo.language,
+                " ".join(repo.topics),
+            ],
+        )
+    ).lower()
+
+
+def categorize_repo(
+    repo: StarredRepo,
+    *,
+    categories: dict[str, list[tuple[str, int]]] | None = None,
+) -> str:
+    rules = categories or CATEGORIES
+    text = _repo_text(repo)
+    scores: dict[str, int] = defaultdict(int)
+
+    for category, patterns in rules.items():
+        for pattern, weight in patterns:
+            if re.search(pattern, text):
+                scores[category] += weight
+
+    if not scores:
+        return DEFAULT_CATEGORY
+
+    max_score = max(scores.values())
+    top = [cat for cat, score in scores.items() if score == max_score]
+
+    if len(top) == 1:
+        return top[0]
+
+    lang = repo.language.lower() if repo.language else ""
+    if lang in LANG_HINTS and LANG_HINTS[lang] in top:
+        return LANG_HINTS[lang]
+
+    return top[0]
+
+
+def build_plan(
+    username: str,
+    repos: list[StarredRepo],
+    *,
+    categories: dict[str, list[tuple[str, int]]] | None = None,
+) -> dict:
+    assignments: dict[str, str] = {}
+    by_list: dict[str, list[str]] = defaultdict(list)
+
+    for repo in repos:
+        category = categorize_repo(repo, categories=categories)
+        assignments[repo.full_name] = category
+        by_list[category].append(repo.full_name)
+
+    return {
+        "username": username,
+        "total": len(repos),
+        "lists": {name: len(items) for name, items in sorted(by_list.items(), key=lambda x: -len(x[1]))},
+        "assignments": assignments,
+    }
+
+
+def save_plan(plan: dict, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(plan, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def load_plan(path: Path) -> dict[str, str]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return data["assignments"]