Star Manager

中文文档 (Simplified Chinese)

Star Manager is a local-first web app for organizing GitHub starred repositories with Star Lists and optional LLM-assisted classification.

Why Star Manager

If you have hundreds of starred repositories, manual list management is slow and inconsistent. Star Manager helps you:

• Sync your starred repositories and Star Lists from GitHub.
• Classify repositories in batches with an OpenAI-compatible LLM.
• Review diffs before any write-back.
• Apply updates to GitHub with explicit progress and issue reporting.
• Keep your working data in browser local storage (IndexedDB via Dexie).

Key Capabilities

• GitHub sync with progress:
  • Fetches starred repositories and Star Lists.
  • Scans list memberships.
  • Supports retry for failed list membership scans.
• Classification pipeline:
  • Two-stage tagging (repo tagging + tag compression).
  • Test mode (small sample) and strict single-tag mode.
  • Diff view against existing Star Lists or a previous classification run.
• Write-back workflow:
  • Preview planned changes (Current vs After) before apply.
  • Creates missing lists when needed during apply.
  • Optional re-plan before apply.
  • Confirms behavior for repos not currently starred.
• Local editing:
  • Assign list memberships per repo in UI before write-back.
• i18n:
  • English/Chinese UI with browser language auto-detection and manual override.

Prerequisites

• Node.js 20+ (LTS recommended)
• pnpm
• A GitHub Personal Access Token (PAT)
• Optional: an OpenAI-compatible LLM endpoint for classification

Quick Start

pnpm install
pnpm dev

Build and preview:

pnpm build
pnpm preview

Configuration

1) GitHub PAT

In the app:

1. Open Settings or Connect PAT.
2. Paste your token.
3. Validate and save.

The token must be able to read your starred repositories and access Star Lists operations for your account. If validation fails, check token scopes/permissions and account feature availability.

2) LLM (Optional)

In Settings -> LLM Configuration, set:

• baseUrl (default: https://api.openai.com/v1)
• apiKey
• model (default: gpt-4o-mini)
• temperature
• maxTokens

You can run classification without changing prompts, or customize prompts for:

• default tagging mode
• strict single-tag mode
• existing-list constrained modes
• English/Chinese prompt variants

Typical Workflow

1. Connect PAT.
2. Click Sync Star Lists.
3. (Optional) Retry failed list membership scans from the status panel.
4. Open Run Classification and run LLM classification.
5. Review preview and diffs.
6. Open Apply Updates to preview planned GitHub changes.
7. Apply updates to GitHub.

Project Structure

src/app/
  App.tsx                 # Main UI shell
  core/                   # Use-cases and orchestration
  services/               # GitHub + LLM clients
  data/                   # Dexie DB and reactive query helpers
  store/                  # Local preferences and LLM config stores
  ui/                     # UI components and modals
  i18n/                   # Translation resources and language helpers
  styles/                 # CSS styles

Data & Privacy

• Local-first storage:
  • App data is stored in browser IndexedDB (star-manager database).
  • Preferences and LLM config are stored in browser local storage.
• PAT and LLM API key are stored locally in your browser.
• The app calls GitHub and your configured LLM endpoint directly from the client.
• Sensitive values should not be logged; avoid sharing browser storage exports.

Troubleshooting

• Star Lists API not available for this token/account
  • Your account or token may not have access to Star Lists GraphQL fields.
• PAT validation failed
  • Re-check token value and permissions; regenerate token if needed.
• LLM test/classification fails
  • Verify baseUrl, apiKey, model, and endpoint compatibility with /chat/completions.
• No repos shown after sync
  • Confirm your account has starred repositories and sync completed successfully.

Known Limitations & Roadmap

Planned next steps include:

• Incremental sync strategy to reduce repeated work.
• Better rate-limit handling and failure recovery.
• Clearer error attribution (permission/token/network categories).
• README cache policy implementation (ETag/hash and truncation strategy).
• Future quality scripts (lint/test) are not configured yet.

Contributing

Contributions are welcome. For substantial changes, open an issue first to discuss scope.

Local commands:

pnpm dev
pnpm build
pnpm preview

License

No LICENSE file is published yet. Until a license is added, redistribution and commercial use terms are not explicitly granted.