diff --git a/CHANGELOG.md b/CHANGELOG.md index 3aece7b..17d8214 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,24 @@ # Changelog +- Mar-19, 2026 - 10:59 PM +08 - [Refined refresh behavior, added tests, and updated docs] + +## [1.4.0] - 2026-03-19 + +### Added +- Unit tests covering cache refresh and embedded star update behavior +- Refresh token warning setting for missing or invalid GitHub tokens +- Repo-local `AGENTS.md` and `dev-docs/SPECS.md` + +### Changed +- `Refresh for current note` now bypasses valid cache entries for repositories in the active note +- Refreshes can update existing embedded stars without embedding plain links +- When enabled, embedded star updates can also happen on Reading View and Live Preview refresh paths +- Updated README and internal specs to match current behavior + +### Fixed +- Invalid GitHub tokens now fall back to unauthenticated requests for public repositories +- Failed refreshes leave existing embedded star text unchanged and show one notice per refresh attempt + ## [1.3.0] - 2026-03-19 ### Removed diff --git a/README.md b/README.md index 635ebd6..5292177 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # GitHub Stars Plugin [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE) -[![Version](https://img.shields.io/badge/version-1.3.0-green?style=for-the-badge)](CHANGELOG.md) +[![Version](https://img.shields.io/badge/version-1.4.0-green?style=for-the-badge)](CHANGELOG.md) [![Obsidian Downloads](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fobsidianmd%2Fobsidian-releases%2FHEAD%2Fcommunity-plugin-stats.json&query=%24%5B%22github-stars%22%5D.downloads&logo=obsidian&label=downloads&style=for-the-badge&color=7C3AED)](https://obsidian.md/plugins?id=github-stars) An Obsidian plugin that automatically displays GitHub star counts next to repository links in your notes — in both Reading View and Live Preview. Star counts can also be embedded directly into your markdown, making them visible outside Obsidian. @@ -38,20 +38,34 @@ The plugin can be configured in the Settings tab: - **Number Format**: Choose between full numbers (e.g., 1,234) or abbreviated format (e.g., 1.2k) - **GitHub API Token**: Optional personal access token to increase the API rate limit from 60 to 5,000 requests per hour. To generate one: 1. Go to [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens) - 2. Click "Generate new token" - 3. Give it a name and select the "public_repo" scope + 2. Create a fine-grained personal access token or a classic token with access suitable for public repository metadata + 3. Give it a name and ensure it can access public repository metadata 4. Click "Generate token" 5. Copy the token and paste it in the plugin settings +- **Update embedded stars on refresh**: Enabled by default. When enabled, refreshing updates the star count written in the Markdown file next to a GitHub URL. +- **Show token warnings on refresh**: Enabled by default. When enabled, the plugin warns during manual refresh if the GitHub token is missing or invalid. + +## 🔄 Refresh And Cache Behavior + +- Rendering in Reading View and Live Preview uses cached star counts when the cache entry is still fresh. +- Cache expiry is lazy. When a cache entry expires, the plugin fetches new data the next time that repository is looked up. Expiry does not trigger a background refresh on its own. +- `Refresh for current note` is stronger than normal rendering. It fetches fresh star counts from GitHub for every repository in the active note even if those cache entries are still valid. +- If `Update embedded stars on refresh` is disabled, embedded star text is left unchanged and may show an older value than the refreshed star count. ## 💻 Commands The plugin adds the following commands: -- **Refresh for current note**: Refreshes all GitHub star counts in the current note +- **Refresh for current note**: Fetches fresh star counts from GitHub for all repositories in the current note and rerenders the note. If `Update embedded stars on refresh` is enabled, it also updates already-embedded star text. - **Clear cache**: Clears the cached star counts - **Embed star counts in current note**: Writes star counts (e.g. `⭐ 1.2k`) directly into the markdown file after each GitHub link. Re-running updates existing counts. - **Remove embedded star counts from current note**: Strips all embedded star counts from the file +## 🧪 Development + +- `npm test`: Runs the unit tests with Vitest +- `npm run build`: Type-checks and builds the plugin bundle + ## ❤️ Support This Project You can support this project in a few simple ways: diff --git a/dev-docs/SPECS.md b/dev-docs/SPECS.md new file mode 100644 index 0000000..2bf4352 --- /dev/null +++ b/dev-docs/SPECS.md @@ -0,0 +1,63 @@ +# Specs + +## Commands + +- `Clear cache` removes all stored cached star counts. +- `Refresh for current note` fetches fresh GitHub star counts for repositories in the active note, updates the cache, and may also update already-embedded star text depending on the refresh setting. +- `Embed star counts in current note` writes star counts into the active note as embedded `⭐ ...` text. +- `Remove embedded star counts from current note` removes embedded `⭐ ...` text from the active note. + +## User Settings + +- `Cache expiry` controls how long cached star counts remain fresh. +- `Number format` controls whether star counts are displayed as full numbers or abbreviated values. +- `GitHub API token (optional)` allows authenticated GitHub API requests for higher rate limits. +- `Update embedded stars on refresh` controls whether refreshes update embedded `⭐ ...` text in the active note. +- `Show token warnings on refresh` controls whether manual refresh warns when the GitHub token is missing or invalid. + +## Refresh Behavior + +- `Refresh for current note` only applies to the active note. +- `Refresh for current note` fetches fresh star counts from GitHub for repositories in the active note even if their cache entries are still valid. +- When `Update embedded stars on refresh` is enabled, refresh updates only links that already have embedded `⭐ ...` text in the active note and then rerenders the note. +- When `Update embedded stars on refresh` is enabled, Reading View and Live Preview refresh paths also update existing embedded `⭐ ...` text for repositories whose star counts were refreshed. +- If the same repository appears multiple times in the active note, refresh fetches it once and applies the result to all matching occurrences. +- When `Update embedded stars on refresh` is disabled, refresh rerenders the note without changing embedded `⭐ ...` text. +- If a refresh fetch fails for a repository, existing embedded star text for that repository is left unchanged. +- If one or more repository refreshes fail during a manual refresh, the plugin shows a single failure notice for that refresh attempt. + +## Rendering Modes + +- Reading View injects star counts into rendered HTML after GitHub repository links. +- Live Preview injects star counts as CodeMirror widgets after visible GitHub repository links. +- Embedded star text in the markdown file is distinct from transient rendered star counts. + +## Embedded Star Rules + +- The plugin detects existing embedded `⭐ ...` text and skips adding duplicate stars during normal rendering. +- Refresh never embeds stars for plain links. It only updates embedded `⭐ ...` text that already exists when the refresh setting is enabled. +- `Embed star counts in current note` writes or updates embedded `⭐ ...` text directly in the markdown file. +- `Remove embedded star counts from current note` removes embedded `⭐ ...` text while leaving the GitHub links intact. + +## Authentication Behavior + +- If no GitHub API token is configured, requests use the lower unauthenticated GitHub API rate limit. +- During a manual refresh of a note, token warnings are shown at most once even if the refresh processes multiple GitHub links. +- If GitHub rejects the configured token, the plugin logs a warning, shows a notice, and retries public repositories without authentication. + +## Cache Behavior + +- GitHub star counts are cached per repository using `owner/repo` as the cache key. +- Each cache entry stores the fetched star count and a timestamp. +- Cache expiry is lazy, not proactive. When an entry expires, the plugin does not schedule or run a background refresh automatically. +- A fresh API request only happens the next time the plugin tries to resolve stars for that repository and sees that the cached entry is missing or expired. +- Star lookups can be triggered by rendering a note in Reading View, rendering visible GitHub links in Live Preview, running `Refresh for current note`, or running `Embed star counts in current note`. +- If a cached entry is still within the configured expiry window, the cached value is used and no network request is made. +- If a request fails and a stale cache entry exists for the same repository, the stale cached value may still be returned. +- Clearing the cache removes stored cache entries but does not remove star text that is already rendered in the current UI. + +## Supported URLs + +- The plugin only processes GitHub repository URLs. +- Repository parsing extracts `owner/repo` from standard GitHub URLs and strips a trailing `.git` suffix from the repository name. +- Non-repository GitHub URLs and malformed links are ignored.