{"id":40627503,"url":"https://github.com/akme/gh-stars-watcher","last_synced_at":"2026-01-21T07:27:51.437Z","repository":{"id":317389031,"uuid":"1066210020","full_name":"akme/gh-stars-watcher","owner":"akme","description":"Monitor GitHub user(s) starred repositories for changes.","archived":false,"fork":false,"pushed_at":"2025-09-30T16:12:08.000Z","size":155,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-30T16:24:36.493Z","etag":null,"topics":["github","go","golang","star"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akme.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-29T07:15:16.000Z","updated_at":"2025-09-30T16:12:11.000Z","dependencies_parsed_at":"2025-09-30T16:25:21.613Z","dependency_job_id":"63fc54e1-6a93-4e19-ba25-629675ea2cf1","html_url":"https://github.com/akme/gh-stars-watcher","commit_stats":null,"previous_names":["akme/gh-stars-watcher"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/akme/gh-stars-watcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akme%2Fgh-stars-watcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akme%2Fgh-stars-watcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akme%2Fgh-stars-watcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akme%2Fgh-stars-watcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akme","download_url":"https://codeload.github.com/akme/gh-stars-watcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akme%2Fgh-stars-watcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28629915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","go","golang","star"],"created_at":"2026-01-21T07:27:51.364Z","updated_at":"2026-01-21T07:27:51.422Z","avatar_url":"https://github.com/akme.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Stars Monitor\n\n[![Go version](https://img.shields.io/github/go-mod/go-version/akme/gh-stars-watcher?style=flat-square)](https://github.com/akme/gh-stars-watcher/blob/main/go.mod)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/akme/gh-stars-watcher/docker.yml?branch=main\u0026style=flat-square\u0026label=build)](https://github.com/akme/gh-stars-watcher/actions/workflows/docker.yml)\n[![Docker Image](https://img.shields.io/badge/docker-2.95MB-blue?style=flat-square\u0026logo=docker)](https://github.com/akme/gh-stars-watcher/pkgs/container/gh-stars-watcher)\n[![License](https://img.shields.io/github/license/akme/gh-stars-watcher?style=flat-square)](LICENSE)\n[![Go Report Card](https://goreportcard.com/badge/github.com/akme/gh-stars-watcher?style=flat-square)](https://goreportcard.com/report/github.com/akme/gh-stars-watcher)\n\nA high-performance command-line tool that tracks changes in GitHub users' starred repositories, showing only newly starred repositories between runs. Designed for automation, monitoring workflows, and integration with other development tools.\n\n## Features\n\n- **Incremental Monitoring**: Only shows newly starred repositories since the last run\n- **Multi-User Support**: Monitor multiple GitHub users simultaneously with parallel processing\n- **First Run Baseline**: Establishes a baseline on the first run without showing output\n- **Multiple Output Formats**: Support for text (human-readable) and JSON formats\n- **Optional Authentication**: Works without tokens (60 req/hour) or with tokens (5000 req/hour) - only prompts when `--auth` flag is used\n- **Secure Token Storage**: Uses OS keychain for token storage with interactive fallback\n- **Rate Limit Handling**: Intelligent rate limit detection and user-friendly error messages\n- **Clean Architecture**: Well-structured codebase with interfaces and dependency injection\n- **Comprehensive Error Handling**: User-friendly error messages with actionable guidance\n\n## Installation\n\n### Prerequisites\n\n- Go 1.25 or later\n- macOS (for keychain integration) or Linux\n\n### Build from Source\n\n```bash\ngit clone https://github.com/akme/gh-stars-watcher.git\ncd gh-stars-watcher\nmake build\n```\n\n## Docker\n\nThe application is available as a multi-architecture Docker image supporting `linux/amd64`, `linux/arm64`, and `linux/arm/v7`.\n\n### Quick Start with Docker\n\n```bash\n# Monitor a user with Docker\ndocker run --rm ghcr.io/akme/gh-stars-watcher:latest monitor octocat\n\n# With JSON output\ndocker run --rm ghcr.io/akme/gh-stars-watcher:latest monitor octocat --output json\n\n# Monitor multiple users\ndocker run --rm ghcr.io/akme/gh-stars-watcher:latest monitor \"octocat,github,torvalds\"\n```\n\n### Persistent State Storage\n\nTo maintain state between runs, mount a volume:\n\n```bash\n# Create a named volume for state persistence\ndocker volume create star-watcher-data\n\n# Run with persistent state\ndocker run --rm \\\n  -v star-watcher-data:/home/nonroot/.star-watcher \\\n  ghcr.io/akme/gh-stars-watcher:latest \\\n  monitor octocat\n```\n\n### With Authentication\n\n```bash\n# Using environment variable\ndocker run --rm \\\n  -e GITHUB_TOKEN=your_token_here \\\n  ghcr.io/akme/gh-stars-watcher:latest \\\n  monitor octocat --auth\n\n# Using Docker secrets (recommended for production)\necho \"your_token_here\" | docker secret create github_token -\ndocker run --rm \\\n  --secret github_token \\\n  -e GITHUB_TOKEN_FILE=/run/secrets/github_token \\\n  ghcr.io/akme/gh-stars-watcher:latest \\\n  monitor octocat --auth\n```\n\n### Docker Compose\n\nUse the included `docker-compose.yml` for easy local development:\n\n```bash\n# Run with Docker Compose\nGITHUB_TOKEN=your_token docker-compose up star-watcher\n\n# Development mode with live code reload\ndocker-compose up star-watcher-dev\n```\n\n### Building Multi-Architecture Images\n\n```bash\n# Build locally\nmake docker-build\n\n# Test multi-arch build\nmake docker-build-multiarch\n\n# Build and push to registry\nmake docker-push\n\n# Build and push with version tag\nmake docker-push-version VERSION=v1.0.0\n\n# Build with version tag\nVERSION=v1.2.0 make docker-push-version\n```\n\n## Usage\n\n### Basic Usage\n\nMonitor a single user's starred repositories:\n\n```bash\n./bin/star-watcher monitor octocat\n```\n\n### Multi-User Monitoring\n\nMonitor multiple users simultaneously with comma-separated usernames:\n\n```bash\n./bin/star-watcher monitor \"octocat,github,torvalds\"\n```\n\nMulti-user example with JSON output:\n\n```bash\n./bin/star-watcher monitor \"octocat,github\" --output json\n```\n\n### First Run\n\nOn the first run, the tool establishes a baseline:\n\n```bash\n$ ./bin/star-watcher monitor octocat\nFirst run for octocat - baseline established with 3 starred repositories.\nRun again to detect newly starred repositories.\n```\n\n### Subsequent Runs\n\nSubsequent runs show only newly starred repositories:\n\n```bash\n$ ./bin/star-watcher monitor octocat\n🌟 octocat has starred 2 new repositories!\n\n⭐ octocat/Hello-World\n   My first repository on GitHub!\n   Language: None | Stars: 1\n   Starred: 2024-01-15\n   https://github.com/octocat/Hello-World\n\n⭐ github/docs\n   The open-source repo for docs.github.com\n   Language: JavaScript | Stars: 2150\n   Starred: 2024-01-16\n   https://github.com/github/docs\n\nTotal repositories: 5\nPrevious check: 2024-01-14 10:30:45\n```\n\n### Multi-User Output\n\nWhen monitoring multiple users, output is grouped by username:\n\n```bash\n$ ./bin/star-watcher monitor \"octocat,github\"\n🌟 octocat has starred 1 new repository!\n\n⭐ octocat/Hello-World\n   My first repository on GitHub!\n   Language: None | Stars: 1\n   Starred: 2024-01-15\n   https://github.com/octocat/Hello-World\n\n🌟 github has starred 1 new repository!\n\n⭐ github/docs\n   The open-source repo for docs.github.com\n   Language: JavaScript | Stars: 2150\n   Starred: 2024-01-16\n   https://github.com/github/docs\n\n=== Summary ===\nTotal users monitored: 2\nUsers with new stars: 2\nTotal new repositories: 2\n```\n\n### JSON Output\n\nGet structured output in JSON format:\n\n```bash\n./bin/star-watcher monitor octocat --output json\n```\n\nSingle user JSON output:\n```json\n{\n  \"username\": \"octocat\",\n  \"new_repositories\": [\n    {\n      \"full_name\": \"octocat/Hello-World\",\n      \"description\": \"My first repository on GitHub!\",\n      \"star_count\": 1,\n      \"updated_at\": \"2024-01-15T10:30:00Z\",\n      \"url\": \"https://github.com/octocat/Hello-World\",\n      \"starred_at\": \"2024-01-15T12:00:00Z\",\n      \"language\": \"\",\n      \"private\": false\n    }\n  ],\n  \"total_repositories\": 5,\n  \"previous_check\": \"2024-01-14T10:30:45Z\",\n  \"current_check\": \"2024-01-16T14:20:30Z\",\n  \"rate_limit\": {\n    \"limit\": 60,\n    \"remaining\": 45,\n    \"reset_time\": \"2024-01-16T15:00:00Z\",\n    \"used\": 15\n  },\n  \"is_first_run\": false\n}\n```\n\nMulti-user JSON output:\n```json\n{\n  \"results\": [\n    {\n      \"username\": \"octocat\",\n      \"new_repositories\": [\n        {\n          \"full_name\": \"octocat/Hello-World\",\n          \"description\": \"My first repository on GitHub!\",\n          \"star_count\": 1,\n          \"updated_at\": \"2024-01-15T10:30:00Z\",\n          \"url\": \"https://github.com/octocat/Hello-World\",\n          \"starred_at\": \"2024-01-15T12:00:00Z\",\n          \"language\": \"\",\n          \"private\": false\n        }\n      ],\n      \"total_repositories\": 3,\n      \"is_first_run\": false\n    },\n    {\n      \"username\": \"github\",\n      \"new_repositories\": [],\n      \"total_repositories\": 50,\n      \"is_first_run\": false\n    }\n  ],\n  \"summary\": {\n    \"total_users\": 2,\n    \"users_with_new_stars\": 1,\n    \"total_new_repositories\": 1\n  },\n  \"timestamp\": \"2024-01-16T14:20:30Z\"\n}\n```\n\n### Cleanup\n\nRemove stored state for a user:\n\n```bash\n./bin/star-watcher cleanup octocat\n```\n\nRemove all stored states:\n\n```bash\n./bin/star-watcher cleanup --all\n```\n\n## Command Reference\n\n### Global Flags\n\n- `-o, --output string`: Output format: `text` (default) or `json`\n- `-q, --quiet`: Quiet output (errors only)\n- `-v, --verbose`: Verbose output (detailed logging)\n- `--state-file string`: Custom state file path (default: `~/.star-watcher/{username}.json`)\n\n### Monitor Command\n\n```bash\nstar-watcher monitor [username] [flags]\n```\n\nMonitor GitHub user(s) starred repositories for changes. Username can be a single user or comma-separated list for multi-user monitoring.\n\n**Flags:**\n- `--auth`: Prompt for GitHub token authentication (optional, increases rate limits)\n- All global flags also apply\n\n**Examples:**\n```bash\nstar-watcher monitor octocat\nstar-watcher monitor octocat --output json\nstar-watcher monitor \"octocat,github,akme\"\nstar-watcher monitor octocat --auth --verbose\nstar-watcher monitor octocat --state-file ./custom-state.json\n```\n\n### Cleanup Command\n\n```bash\nstar-watcher cleanup [username] [flags]\n```\n\nRemove stored state files for a specific user or all users.\n\n**Flags:**\n- `--all`: Remove all state files (use with caution)\n\n**Examples:**\n```bash\nstar-watcher cleanup octocat\nstar-watcher cleanup octocat --state-file ./custom-state.json\nstar-watcher cleanup --all\n```\n\n## Authentication\n\n**Authentication is completely optional!** The tool works without authentication, but provides higher rate limits when authenticated.\n\n### Authentication Options\n\n1. **No Authentication** (default): 60 requests per hour - sufficient for monitoring a few users\n2. **With Authentication**: 5000 requests per hour - use the `--auth` flag to enable\n\n### Authentication Methods (when using `--auth`)\n\n1. **Environment Variable**: Set `GITHUB_TOKEN` environment variable\n2. **OS Keychain**: Tokens are securely stored in the system keychain\n3. **Interactive Prompt**: If no token is found, you'll be prompted to enter one\n\n### Using Authentication\n\nOnly prompt for authentication when you need higher rate limits:\n\n```bash\n# Use without authentication (60 req/hour)\n./bin/star-watcher monitor octocat\n\n# Use with authentication (5000 req/hour)\n./bin/star-watcher monitor octocat --auth\n```\n\n### Creating a GitHub Token\n\n1. Go to [GitHub Settings \u003e Personal Access Tokens](https://github.com/settings/tokens)\n2. Click \"Generate new token (classic)\"\n3. Add a note (e.g., \"GitHub Stars Monitor\")\n4. Select scopes:\n   - `public_repo` (for public repositories)\n   - `repo` (if you want to monitor private starred repositories)\n5. Click \"Generate token\"\n6. Copy the token and provide it when prompted\n\n## State Storage\n\nThe tool stores state in JSON files under `~/.star-watcher/`:\n\n- `~/.star-watcher/{username}.json`: Contains the baseline of starred repositories for each user\n- Files include repository metadata, star counts, and timestamps\n- State files are atomic-write protected to prevent corruption\n- Each user has independent state management for multi-user monitoring\n- Significantly reduced file sizes - removed unnecessary audit logging to keep files minimal\n\n## Rate Limiting\n\n- **Unauthenticated**: 60 requests per hour\n- **Authenticated**: 5000 requests per hour\n\nThe tool automatically handles rate limits and provides helpful error messages:\n\n```bash\nError: GitHub API rate limit exceeded. Resets at: 2024-01-16T15:00:00Z\n```\n\n## Architecture\n\nThe project follows clean architecture principles:\n\n```\ncmd/star-watcher/          # CLI entry point\ninternal/\n├── auth/                  # Authentication (keychain, prompts)\n├── cli/                   # CLI commands and output formatting\n├── github/                # GitHub API client\n├── monitor/               # Core monitoring logic\n└── storage/               # State persistence\ntests/\n├── contract/              # Interface contract tests\n└── integration/           # End-to-end tests\n```\n\n## Development\n\n### Building\n\n```bash\ngo build -o star-watcher ./cmd/star-watcher\n```\n\n### Testing\n\n```bash\ngo test ./...\n```\n\n### Code Style\n\nThe project follows standard Go conventions and uses:\n\n- Clean architecture with interfaces\n- Dependency injection\n- Comprehensive error handling\n- Test-driven development (TDD)\n\n## Performance\n\n- **Startup Time**: ~20ms for CLI operations\n- **API Performance**: ~50 seconds for 3000 repositories (limited by GitHub API)\n- **State File Size**: Significantly reduced - removed unnecessary audit logging (timestamps) for minimal file sizes\n- **Memory Usage**: Minimal - processes repositories in batches\n- **Multi-User Processing**: Parallel processing for multiple users with goroutines\n- **Rate Limit Optimization**: Intelligent handling for both authenticated (5000/hour) and unauthenticated (60/hour) usage\n\n## Troubleshooting\n\n### Rate Limit Exceeded\n\nWait for the rate limit to reset or authenticate with a GitHub token for higher limits.\n\n### Invalid Username Format\n\nEnsure the username follows GitHub's rules:\n- 1-39 characters long\n- Only alphanumeric characters and hyphens\n- Cannot start or end with a hyphen\n\n### State File Corruption\n\nRemove the state file and re-run to establish a new baseline:\n\n```bash\nstar-watcher cleanup username\nstar-watcher monitor username\n```\n\n### Permission Errors\n\nEnsure the tool has permission to write to `~/.star-watcher/` directory.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes following the existing code style\n4. Add tests for new functionality\n5. Ensure all tests pass (`go test ./...`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [go-github](https://github.com/google/go-github) for GitHub API integration\n- [Cobra](https://github.com/spf13/cobra) for CLI framework\n- [go-keyring](https://github.com/zalando/go-keyring) for secure token storage\n- `tests/` - Comprehensive test suite (contract, integration, unit)\n\n## License\n\nMIT License - see LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakme%2Fgh-stars-watcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakme%2Fgh-stars-watcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakme%2Fgh-stars-watcher/lists"}