github-stars-organizer 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- github_stars_organizer-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md +27 -0
- github_stars_organizer-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md +18 -0
- github_stars_organizer-0.2.0/.github/workflows/ci.yml +36 -0
- github_stars_organizer-0.2.0/.github/workflows/release.yml +26 -0
- github_stars_organizer-0.2.0/.gitignore +31 -0
- github_stars_organizer-0.2.0/ATTRIBUTION.md +16 -0
- github_stars_organizer-0.2.0/CHANGELOG.md +29 -0
- github_stars_organizer-0.2.0/CONTRIBUTING.md +37 -0
- github_stars_organizer-0.2.0/LICENSE +21 -0
- github_stars_organizer-0.2.0/PKG-INFO +209 -0
- github_stars_organizer-0.2.0/PUBLISH.md +45 -0
- github_stars_organizer-0.2.0/README.md +181 -0
- github_stars_organizer-0.2.0/SECURITY.md +27 -0
- github_stars_organizer-0.2.0/categories.example.toml +15 -0
- github_stars_organizer-0.2.0/config.example.toml +17 -0
- github_stars_organizer-0.2.0/examples/examples/plan.example.json +14 -0
- github_stars_organizer-0.2.0/examples/plan.example.json +14 -0
- github_stars_organizer-0.2.0/pyproject.toml +66 -0
- github_stars_organizer-0.2.0/src/stars_organizer/__init__.py +3 -0
- github_stars_organizer-0.2.0/src/stars_organizer/__main__.py +4 -0
- github_stars_organizer-0.2.0/src/stars_organizer/apply.py +155 -0
- github_stars_organizer-0.2.0/src/stars_organizer/categorize.py +177 -0
- github_stars_organizer-0.2.0/src/stars_organizer/cli.py +205 -0
- github_stars_organizer-0.2.0/src/stars_organizer/config.py +83 -0
- github_stars_organizer-0.2.0/src/stars_organizer/github_api.py +79 -0
- github_stars_organizer-0.2.0/src/stars_organizer/github_web.py +358 -0
- github_stars_organizer-0.2.0/src/stars_organizer/llm_categorize.py +140 -0
- github_stars_organizer-0.2.0/src/stars_organizer/models.py +48 -0
- github_stars_organizer-0.2.0/src/stars_organizer/state.py +32 -0
- github_stars_organizer-0.2.0/tests/test_apply_guard.py +5 -0
- github_stars_organizer-0.2.0/tests/test_categorize.py +69 -0
- github_stars_organizer-0.2.0/tests/test_config.py +32 -0
- github_stars_organizer-0.2.0/tests/test_plan_format.py +42 -0
- github_stars_organizer-0.2.0/uv.lock +505 -0
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Bug report
|
|
3
|
+
about: Report something that isn't working
|
|
4
|
+
title: "[Bug] "
|
|
5
|
+
labels: bug
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
**Describe the bug**
|
|
9
|
+
A clear description of what went wrong.
|
|
10
|
+
|
|
11
|
+
**To reproduce**
|
|
12
|
+
Steps to reproduce:
|
|
13
|
+
1. Run `organize-stars ...`
|
|
14
|
+
2. ...
|
|
15
|
+
|
|
16
|
+
**Expected behavior**
|
|
17
|
+
What you expected to happen.
|
|
18
|
+
|
|
19
|
+
**Environment**
|
|
20
|
+
- OS:
|
|
21
|
+
- Python version:
|
|
22
|
+
- github-stars-organizer version:
|
|
23
|
+
|
|
24
|
+
**Error output**
|
|
25
|
+
```
|
|
26
|
+
Paste error message here (redact tokens/cookies)
|
|
27
|
+
```
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Feature request
|
|
3
|
+
about: Suggest an idea for this project
|
|
4
|
+
title: "[Feature] "
|
|
5
|
+
labels: enhancement
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
**Problem**
|
|
9
|
+
What problem does this solve?
|
|
10
|
+
|
|
11
|
+
**Proposed solution**
|
|
12
|
+
How would you like it to work?
|
|
13
|
+
|
|
14
|
+
**Alternatives considered**
|
|
15
|
+
Any other approaches you've thought about.
|
|
16
|
+
|
|
17
|
+
**Additional context**
|
|
18
|
+
Screenshots, examples, or links if helpful.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main, master]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main, master]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ${{ matrix.os }}
|
|
12
|
+
strategy:
|
|
13
|
+
fail-fast: false
|
|
14
|
+
matrix:
|
|
15
|
+
os: [ubuntu-latest, windows-latest]
|
|
16
|
+
python-version: ["3.12", "3.13"]
|
|
17
|
+
|
|
18
|
+
steps:
|
|
19
|
+
- uses: actions/checkout@v4
|
|
20
|
+
|
|
21
|
+
- name: Install uv
|
|
22
|
+
uses: astral-sh/setup-uv@v5
|
|
23
|
+
with:
|
|
24
|
+
enable-cache: true
|
|
25
|
+
|
|
26
|
+
- name: Set up Python
|
|
27
|
+
run: uv python install ${{ matrix.python-version }}
|
|
28
|
+
|
|
29
|
+
- name: Install dependencies
|
|
30
|
+
run: uv sync --dev
|
|
31
|
+
|
|
32
|
+
- name: Ruff
|
|
33
|
+
run: uv run ruff check .
|
|
34
|
+
|
|
35
|
+
- name: Pytest
|
|
36
|
+
run: uv run pytest
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags:
|
|
6
|
+
- "v*"
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
publish:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
environment: pypi
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v4
|
|
17
|
+
|
|
18
|
+
- uses: astral-sh/setup-uv@v5
|
|
19
|
+
|
|
20
|
+
- name: Build
|
|
21
|
+
run: uv build
|
|
22
|
+
|
|
23
|
+
- name: Publish to PyPI
|
|
24
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
25
|
+
with:
|
|
26
|
+
password: ${{ secrets.PYPI_API_TOKEN }}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Secrets
|
|
2
|
+
config.toml
|
|
3
|
+
categories.toml
|
|
4
|
+
*.local.json
|
|
5
|
+
|
|
6
|
+
# User-generated plans (keep examples/ only)
|
|
7
|
+
categorization-plan.json
|
|
8
|
+
.organize-stars-state.json
|
|
9
|
+
|
|
10
|
+
# Dev notes (local only)
|
|
11
|
+
devlog.md
|
|
12
|
+
learning-journal.md
|
|
13
|
+
examples/*-sample-plan.json
|
|
14
|
+
|
|
15
|
+
# Python
|
|
16
|
+
__pycache__/
|
|
17
|
+
*.py[cod]
|
|
18
|
+
*.egg-info/
|
|
19
|
+
.venv/
|
|
20
|
+
dist/
|
|
21
|
+
build/
|
|
22
|
+
.uv/
|
|
23
|
+
|
|
24
|
+
# IDE / OS
|
|
25
|
+
.vscode/
|
|
26
|
+
.idea/
|
|
27
|
+
.DS_Store
|
|
28
|
+
Thumbs.db
|
|
29
|
+
|
|
30
|
+
# Legacy vendored clone
|
|
31
|
+
tool/
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Attribution
|
|
2
|
+
|
|
3
|
+
## github_web.py
|
|
4
|
+
|
|
5
|
+
The GitHub Star Lists web client in `src/stars_organizer/github_web.py` is adapted from:
|
|
6
|
+
|
|
7
|
+
- **Project:** [github-star-organizer](https://github.com/luoling8192/github-star-organizer)
|
|
8
|
+
- **Author:** luoling8192
|
|
9
|
+
- **License:** MIT
|
|
10
|
+
|
|
11
|
+
That upstream project reverse-engineered GitHub's unofficial web endpoints for creating lists and assigning starred repositories. This project reuses that approach with heuristic categorization instead of LLM-based sorting.
|
|
12
|
+
|
|
13
|
+
## Related projects
|
|
14
|
+
|
|
15
|
+
- [github-manage-stars-unofficial (ghstars)](https://github.com/snowfluke/github-manage-stars-unofficial)
|
|
16
|
+
- [starred](https://github.com/amirhmoradi/starred)
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.2.0] - 2026-06-08
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- `organize-stars init` — interactive config setup
|
|
8
|
+
- `organize-stars status` — config and resume state check
|
|
9
|
+
- `organize-stars lists` — show current Star Lists
|
|
10
|
+
- `organize-stars plan --categories` — custom `categories.toml` rules
|
|
11
|
+
- `organize-stars plan --llm` — optional AI categorization (`uv sync --extra llm`)
|
|
12
|
+
- `organize-stars apply --resume` — checkpoint resume via `.organize-stars-state.json`
|
|
13
|
+
- Rich progress bar during apply
|
|
14
|
+
- PyPI publish workflow on version tags
|
|
15
|
+
|
|
16
|
+
### Fixed
|
|
17
|
+
|
|
18
|
+
- Removed Python → AI & LLM language bias
|
|
19
|
+
- Language hints used as tie-breakers only
|
|
20
|
+
- Pre-apply guard when plan exceeds GitHub's 32-list limit
|
|
21
|
+
|
|
22
|
+
## [0.1.0] - 2026-06-08
|
|
23
|
+
|
|
24
|
+
### Added
|
|
25
|
+
|
|
26
|
+
- `organize-stars plan` — fetch stars and build categorization plan
|
|
27
|
+
- `organize-stars apply` — create Star Lists and assign repos
|
|
28
|
+
- Heuristic categorization (no LLM required)
|
|
29
|
+
- MIT license, tests, CI
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Thanks for helping improve GitHub Stars Organizer!
|
|
4
|
+
|
|
5
|
+
## Development setup
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
git clone https://github.com/nishal21/github-stars-organizer.git
|
|
9
|
+
cd github-stars-organizer
|
|
10
|
+
uv sync --dev
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Run tests
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
uv run pytest
|
|
17
|
+
uv run ruff check .
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Adding category rules
|
|
21
|
+
|
|
22
|
+
**Default rules:** edit [`src/stars_organizer/categorize.py`](src/stars_organizer/categorize.py)
|
|
23
|
+
|
|
24
|
+
**User-facing rules:** add patterns to `categories.toml` (see [`categories.example.toml`](categories.example.toml))
|
|
25
|
+
|
|
26
|
+
Add a test case in [`tests/test_categorize.py`](tests/test_categorize.py) for new default rules.
|
|
27
|
+
|
|
28
|
+
## Pull requests
|
|
29
|
+
|
|
30
|
+
1. Fork and create a feature branch
|
|
31
|
+
2. Keep changes focused
|
|
32
|
+
3. Ensure CI passes (`pytest` + `ruff`)
|
|
33
|
+
4. Update [`CHANGELOG.md`](CHANGELOG.md) for user-visible changes
|
|
34
|
+
|
|
35
|
+
## Reporting issues
|
|
36
|
+
|
|
37
|
+
Use the bug report or feature request templates on GitHub Issues.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 nishal21
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: github-stars-organizer
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Organize GitHub starred repos into Star Lists — free heuristic categorization, optional LLM
|
|
5
|
+
Project-URL: Homepage, https://github.com/nishal21/github-stars-organizer
|
|
6
|
+
Project-URL: Repository, https://github.com/nishal21/github-stars-organizer
|
|
7
|
+
Project-URL: Issues, https://github.com/nishal21/github-stars-organizer/issues
|
|
8
|
+
Author-email: Nishal K <nishal21@users.noreply.github.com>
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: cli,developer-tools,github,organize,productivity,stars
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
20
|
+
Classifier: Topic :: Utilities
|
|
21
|
+
Requires-Python: >=3.12
|
|
22
|
+
Requires-Dist: beautifulsoup4>=4.12
|
|
23
|
+
Requires-Dist: httpx>=0.27
|
|
24
|
+
Requires-Dist: rich>=13.0
|
|
25
|
+
Provides-Extra: llm
|
|
26
|
+
Requires-Dist: openai>=1.0; extra == 'llm'
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# GitHub Stars Organizer
|
|
30
|
+
|
|
31
|
+
[](LICENSE)
|
|
32
|
+
[](https://www.python.org/downloads/)
|
|
33
|
+
[](https://github.com/nishal21/github-stars-organizer/actions/workflows/ci.yml)
|
|
34
|
+
|
|
35
|
+
**Organize 300+ GitHub stars into lists in minutes — free, no AI required.**
|
|
36
|
+
|
|
37
|
+
GitHub's official API can star/unstar repos, but **cannot create or manage Star Lists**. This CLI:
|
|
38
|
+
|
|
39
|
+
1. Fetches your starred repos (public GitHub API)
|
|
40
|
+
2. Categorizes them by name, description, language, and topics
|
|
41
|
+
3. Creates lists and assigns repos via your browser session
|
|
42
|
+
|
|
43
|
+
### Why this tool?
|
|
44
|
+
|
|
45
|
+
| Tool | Drawback | This project |
|
|
46
|
+
|------|----------|--------------|
|
|
47
|
+
| [github-star-organizer](https://github.com/luoling8192/github-star-organizer) | Requires paid LLM API | **Free heuristic by default** |
|
|
48
|
+
| [ghstars](https://github.com/snowfluke/github-manage-stars-unofficial) | Manual category files only | **Auto-plan + custom rules + optional LLM** |
|
|
49
|
+
| [starred](https://github.com/amirhmoradi/starred) | AI-first, complex | **Simple: plan → review → apply** |
|
|
50
|
+
|
|
51
|
+
## Install
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
# From source
|
|
55
|
+
git clone https://github.com/nishal21/github-stars-organizer.git
|
|
56
|
+
cd github-stars-organizer
|
|
57
|
+
uv sync
|
|
58
|
+
|
|
59
|
+
# Or from PyPI (after v0.2.0 release)
|
|
60
|
+
pip install github-stars-organizer
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/) (recommended).
|
|
64
|
+
|
|
65
|
+
## Quick start
|
|
66
|
+
|
|
67
|
+
### 1. Build a plan (no credentials needed)
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
organize-stars plan --username YOUR_USERNAME
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Review `categorization-plan.json`. Edit assignments or add custom rules:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
cp categories.example.toml categories.toml
|
|
77
|
+
# edit categories.toml
|
|
78
|
+
organize-stars plan --username YOUR_USERNAME --categories categories.toml
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### 2. Configure credentials
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
organize-stars init
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Or copy and edit manually:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
cp config.example.toml config.toml
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
| Field | How to get it |
|
|
94
|
+
|-------|----------------|
|
|
95
|
+
| `username` | Your GitHub username |
|
|
96
|
+
| `token` | [GitHub token settings](https://github.com/settings/tokens) (classic; `public_repo` if you star private repos) |
|
|
97
|
+
| `cookies` | See [Getting your cookie](#getting-your-browser-cookie) below |
|
|
98
|
+
|
|
99
|
+
### 3. Preview and apply
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
organize-stars apply --dry-run
|
|
103
|
+
organize-stars apply
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
View result: `https://github.com/YOUR_USERNAME?tab=stars`
|
|
107
|
+
|
|
108
|
+
If interrupted, resume with:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
organize-stars apply --resume
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Getting your browser cookie
|
|
115
|
+
|
|
116
|
+
GitHub Star Lists have no public API — applying lists uses your browser session.
|
|
117
|
+
|
|
118
|
+
1. Log into [github.com](https://github.com) in Chrome or Edge
|
|
119
|
+
2. Press **F12** to open DevTools
|
|
120
|
+
3. Open the **Network** tab
|
|
121
|
+
4. Refresh the page
|
|
122
|
+
5. Click any request to `github.com`
|
|
123
|
+
6. Under **Headers**, find **Cookie**
|
|
124
|
+
7. Copy the **entire** cookie string into `config.toml` → `[github.session]` → `cookies`
|
|
125
|
+
|
|
126
|
+
Cookies expire every few weeks. Refresh from DevTools if you get CSRF or 403 errors.
|
|
127
|
+
|
|
128
|
+
## CLI reference
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
organize-stars init [--config config.toml] [--force]
|
|
132
|
+
organize-stars status [--config config.toml]
|
|
133
|
+
organize-stars lists [--config config.toml]
|
|
134
|
+
|
|
135
|
+
organize-stars plan --username USER [--categories categories.toml] [--output plan.json]
|
|
136
|
+
organize-stars plan --config config.toml [--categories categories.toml]
|
|
137
|
+
organize-stars plan --config config.toml --llm # optional AI mode
|
|
138
|
+
|
|
139
|
+
organize-stars apply [--config config.toml] [--plan plan.json] [--dry-run] [--yes] [--resume]
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Optional LLM mode
|
|
143
|
+
|
|
144
|
+
For smarter categorization, add a `[llm]` section to `config.toml` and install the extra:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
uv sync --extra llm
|
|
148
|
+
organize-stars plan --config config.toml --llm
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Heuristic mode remains the default — no API key required.
|
|
152
|
+
|
|
153
|
+
## Default categories
|
|
154
|
+
|
|
155
|
+
- AI & LLM
|
|
156
|
+
- Web Dev & Frontend
|
|
157
|
+
- Mobile & Android
|
|
158
|
+
- Backend & APIs
|
|
159
|
+
- Dev Tools & CLI
|
|
160
|
+
- Self-hosting & DevOps
|
|
161
|
+
- Security & Privacy
|
|
162
|
+
- Media & Creative
|
|
163
|
+
- Gaming & Entertainment
|
|
164
|
+
- Go & Systems
|
|
165
|
+
- Learning & Inspiration
|
|
166
|
+
- Misc & Tools
|
|
167
|
+
|
|
168
|
+
Customize via `categories.toml` or edit the plan JSON before applying.
|
|
169
|
+
|
|
170
|
+
## Troubleshooting
|
|
171
|
+
|
|
172
|
+
| Problem | Fix |
|
|
173
|
+
|---------|-----|
|
|
174
|
+
| CSRF / 403 error | Refresh browser cookie in `config.toml` |
|
|
175
|
+
| Rate limited | Wait a few minutes; reduce `concurrency` in config |
|
|
176
|
+
| More than 32 lists | GitHub hard limit — merge categories in plan or `categories.toml` |
|
|
177
|
+
| Apply interrupted | Run `organize-stars apply --resume` |
|
|
178
|
+
| `config.toml not found` | Run `organize-stars init` |
|
|
179
|
+
|
|
180
|
+
Check setup anytime:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
organize-stars status
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## Privacy and security
|
|
187
|
+
|
|
188
|
+
- Token and cookies stay in local `config.toml` (gitignored) — never commit them
|
|
189
|
+
- Plan mode reads only **public** repo metadata
|
|
190
|
+
- LLM mode (optional) sends metadata to your configured provider
|
|
191
|
+
- See [SECURITY.md](SECURITY.md)
|
|
192
|
+
|
|
193
|
+
## Development
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
uv sync --dev
|
|
197
|
+
uv run pytest
|
|
198
|
+
uv run ruff check .
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
202
|
+
|
|
203
|
+
## Attribution
|
|
204
|
+
|
|
205
|
+
Web client adapted from [luoling8192/github-star-organizer](https://github.com/luoling8192/github-star-organizer) (MIT). See [ATTRIBUTION.md](ATTRIBUTION.md).
|
|
206
|
+
|
|
207
|
+
## License
|
|
208
|
+
|
|
209
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Publishing guide
|
|
2
|
+
|
|
3
|
+
## GitHub repository
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
cd github-stars-organizer
|
|
7
|
+
git branch -M main
|
|
8
|
+
git add .
|
|
9
|
+
git commit -m "Initial release v0.2.0"
|
|
10
|
+
gh repo create nishal21/github-stars-organizer --public --source=. --remote=origin --push
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Add topics on GitHub: `github`, `cli`, `python`, `stars`, `productivity`, `open-source`
|
|
14
|
+
|
|
15
|
+
## Dogfood (organize your stars)
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
organize-stars init
|
|
19
|
+
organize-stars plan --username nishal21
|
|
20
|
+
organize-stars apply --dry-run
|
|
21
|
+
organize-stars apply
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Screenshot https://github.com/nishal21?tab=stars and add to README.
|
|
25
|
+
|
|
26
|
+
## PyPI release
|
|
27
|
+
|
|
28
|
+
1. Create account at https://pypi.org
|
|
29
|
+
2. Create API token
|
|
30
|
+
3. Add `PYPI_API_TOKEN` secret to GitHub repo settings
|
|
31
|
+
4. Tag and push:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
git tag v0.2.0
|
|
35
|
+
git push origin v0.2.0
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The release workflow publishes automatically.
|
|
39
|
+
|
|
40
|
+
Manual publish:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
uv build
|
|
44
|
+
uv publish --token $PYPI_API_TOKEN
|
|
45
|
+
```
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
# GitHub Stars Organizer
|
|
2
|
+
|
|
3
|
+
[](LICENSE)
|
|
4
|
+
[](https://www.python.org/downloads/)
|
|
5
|
+
[](https://github.com/nishal21/github-stars-organizer/actions/workflows/ci.yml)
|
|
6
|
+
|
|
7
|
+
**Organize 300+ GitHub stars into lists in minutes — free, no AI required.**
|
|
8
|
+
|
|
9
|
+
GitHub's official API can star/unstar repos, but **cannot create or manage Star Lists**. This CLI:
|
|
10
|
+
|
|
11
|
+
1. Fetches your starred repos (public GitHub API)
|
|
12
|
+
2. Categorizes them by name, description, language, and topics
|
|
13
|
+
3. Creates lists and assigns repos via your browser session
|
|
14
|
+
|
|
15
|
+
### Why this tool?
|
|
16
|
+
|
|
17
|
+
| Tool | Drawback | This project |
|
|
18
|
+
|------|----------|--------------|
|
|
19
|
+
| [github-star-organizer](https://github.com/luoling8192/github-star-organizer) | Requires paid LLM API | **Free heuristic by default** |
|
|
20
|
+
| [ghstars](https://github.com/snowfluke/github-manage-stars-unofficial) | Manual category files only | **Auto-plan + custom rules + optional LLM** |
|
|
21
|
+
| [starred](https://github.com/amirhmoradi/starred) | AI-first, complex | **Simple: plan → review → apply** |
|
|
22
|
+
|
|
23
|
+
## Install
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
# From source
|
|
27
|
+
git clone https://github.com/nishal21/github-stars-organizer.git
|
|
28
|
+
cd github-stars-organizer
|
|
29
|
+
uv sync
|
|
30
|
+
|
|
31
|
+
# Or from PyPI (after v0.2.0 release)
|
|
32
|
+
pip install github-stars-organizer
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/) (recommended).
|
|
36
|
+
|
|
37
|
+
## Quick start
|
|
38
|
+
|
|
39
|
+
### 1. Build a plan (no credentials needed)
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
organize-stars plan --username YOUR_USERNAME
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Review `categorization-plan.json`. Edit assignments or add custom rules:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
cp categories.example.toml categories.toml
|
|
49
|
+
# edit categories.toml
|
|
50
|
+
organize-stars plan --username YOUR_USERNAME --categories categories.toml
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### 2. Configure credentials
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
organize-stars init
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Or copy and edit manually:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
cp config.example.toml config.toml
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
| Field | How to get it |
|
|
66
|
+
|-------|----------------|
|
|
67
|
+
| `username` | Your GitHub username |
|
|
68
|
+
| `token` | [GitHub token settings](https://github.com/settings/tokens) (classic; `public_repo` if you star private repos) |
|
|
69
|
+
| `cookies` | See [Getting your cookie](#getting-your-browser-cookie) below |
|
|
70
|
+
|
|
71
|
+
### 3. Preview and apply
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
organize-stars apply --dry-run
|
|
75
|
+
organize-stars apply
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
View result: `https://github.com/YOUR_USERNAME?tab=stars`
|
|
79
|
+
|
|
80
|
+
If interrupted, resume with:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
organize-stars apply --resume
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Getting your browser cookie
|
|
87
|
+
|
|
88
|
+
GitHub Star Lists have no public API — applying lists uses your browser session.
|
|
89
|
+
|
|
90
|
+
1. Log into [github.com](https://github.com) in Chrome or Edge
|
|
91
|
+
2. Press **F12** to open DevTools
|
|
92
|
+
3. Open the **Network** tab
|
|
93
|
+
4. Refresh the page
|
|
94
|
+
5. Click any request to `github.com`
|
|
95
|
+
6. Under **Headers**, find **Cookie**
|
|
96
|
+
7. Copy the **entire** cookie string into `config.toml` → `[github.session]` → `cookies`
|
|
97
|
+
|
|
98
|
+
Cookies expire every few weeks. Refresh from DevTools if you get CSRF or 403 errors.
|
|
99
|
+
|
|
100
|
+
## CLI reference
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
organize-stars init [--config config.toml] [--force]
|
|
104
|
+
organize-stars status [--config config.toml]
|
|
105
|
+
organize-stars lists [--config config.toml]
|
|
106
|
+
|
|
107
|
+
organize-stars plan --username USER [--categories categories.toml] [--output plan.json]
|
|
108
|
+
organize-stars plan --config config.toml [--categories categories.toml]
|
|
109
|
+
organize-stars plan --config config.toml --llm # optional AI mode
|
|
110
|
+
|
|
111
|
+
organize-stars apply [--config config.toml] [--plan plan.json] [--dry-run] [--yes] [--resume]
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Optional LLM mode
|
|
115
|
+
|
|
116
|
+
For smarter categorization, add a `[llm]` section to `config.toml` and install the extra:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
uv sync --extra llm
|
|
120
|
+
organize-stars plan --config config.toml --llm
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Heuristic mode remains the default — no API key required.
|
|
124
|
+
|
|
125
|
+
## Default categories
|
|
126
|
+
|
|
127
|
+
- AI & LLM
|
|
128
|
+
- Web Dev & Frontend
|
|
129
|
+
- Mobile & Android
|
|
130
|
+
- Backend & APIs
|
|
131
|
+
- Dev Tools & CLI
|
|
132
|
+
- Self-hosting & DevOps
|
|
133
|
+
- Security & Privacy
|
|
134
|
+
- Media & Creative
|
|
135
|
+
- Gaming & Entertainment
|
|
136
|
+
- Go & Systems
|
|
137
|
+
- Learning & Inspiration
|
|
138
|
+
- Misc & Tools
|
|
139
|
+
|
|
140
|
+
Customize via `categories.toml` or edit the plan JSON before applying.
|
|
141
|
+
|
|
142
|
+
## Troubleshooting
|
|
143
|
+
|
|
144
|
+
| Problem | Fix |
|
|
145
|
+
|---------|-----|
|
|
146
|
+
| CSRF / 403 error | Refresh browser cookie in `config.toml` |
|
|
147
|
+
| Rate limited | Wait a few minutes; reduce `concurrency` in config |
|
|
148
|
+
| More than 32 lists | GitHub hard limit — merge categories in plan or `categories.toml` |
|
|
149
|
+
| Apply interrupted | Run `organize-stars apply --resume` |
|
|
150
|
+
| `config.toml not found` | Run `organize-stars init` |
|
|
151
|
+
|
|
152
|
+
Check setup anytime:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
organize-stars status
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## Privacy and security
|
|
159
|
+
|
|
160
|
+
- Token and cookies stay in local `config.toml` (gitignored) — never commit them
|
|
161
|
+
- Plan mode reads only **public** repo metadata
|
|
162
|
+
- LLM mode (optional) sends metadata to your configured provider
|
|
163
|
+
- See [SECURITY.md](SECURITY.md)
|
|
164
|
+
|
|
165
|
+
## Development
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
uv sync --dev
|
|
169
|
+
uv run pytest
|
|
170
|
+
uv run ruff check .
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
174
|
+
|
|
175
|
+
## Attribution
|
|
176
|
+
|
|
177
|
+
Web client adapted from [luoling8192/github-star-organizer](https://github.com/luoling8192/github-star-organizer) (MIT). See [ATTRIBUTION.md](ATTRIBUTION.md).
|
|
178
|
+
|
|
179
|
+
## License
|
|
180
|
+
|
|
181
|
+
MIT — see [LICENSE](LICENSE).
|