Introduction & Features Overview

Refined GitHub Projects (RGP) is a browser extension designed to enhance GitHub Projects V2 by providing advanced bulk operations, sprint management tools, and deep item duplication. The project operates entirely within the browser, utilizing GitHub's GraphQL API to perform mutations that are otherwise unavailable or cumbersome in the native interface. By leveraging a background sequential queue, the system ensures rate-limit safety and provides real-time progress tracking for complex operations.

Sources: README.md:1-12, README.md:46-55

Core Architecture & System Design

The application follows a decoupled architecture involving a Content Script, a Background Service Worker, and an Extension Popup. The Content Script is responsible for DOM observation and UI injection via a Shadow DOM to prevent style clashing with GitHub's native interface. High-privilege operations, such as API calls and PAT (Personal Access Token) management, are restricted to the Background Service Worker.

The diagram above illustrates the multi-layered data flow where the UI triggers messages to the background worker, which then manages a sequential queue to interact with GitHub APIs.
Sources: README.md:213-231, src/entries/background/helpers.ts:241-267

Sequential Task Queue

A critical architectural constraint of the project is the prohibition of concurrent mutations. To avoid 403-rate-limiting or PAT bans, all API writes must pass through a sequential queue with a mandatory 1-second delay (sleep(1000)) between each mutation.

Sources: CONTRIBUTING.md:12-16, src/entries/background/helpers.ts:544-548

Primary Features

Bulk Edit Wizard

The Bulk Edit Wizard allows users to modify standard and custom fields across multiple items simultaneously. It utilizes a three-step flow: field selection, value setting, and a final review diff.

Sources: src/components/bulk/bulk-edit-modal.tsx:431-520, README.md:105-115

Deep Duplicate

Unlike GitHub's native duplication, RGP's Deep Duplicate clones all item properties, including labels, assignees, sub-issue relationships, and full body content. It uses getItemPreview to fetch original state before creating a DuplicateItemPlan.

This sequence shows how the extension first gathers detailed metadata to ensure a high-fidelity clone of the project item.
Sources: src/components/bulk/bulk-duplicate-modal.tsx:415-460, src/entries/background/handlers/hierarchy-handlers.ts:40-100

Sprint & Hierarchy Management

RGP introduces specialized handlers for managing project hierarchies and sprint rollovers. The HierarchyData structure tracks sub-issues and completion states, while the Sprint Management feature allows for one-click closing of iterations with automatic migration of incomplete items to the next sprint.

Sources: src/entries/background/handlers/hierarchy-handlers.ts:208-255, README.md:125-131

Technical Implementation Details

Data Resolution

The extension often interacts with the DOM using temporary IDs (e.g., issue:3960969873). The background helper resolveProjectItemIds is used to convert these into permanent GitHub Global Node IDs required for GraphQL mutations.

// Example of ID resolution logic
export async function resolveProjectItemIds(
  domIds: string[],
  projectId: string,
  tabId?: number,
): Promise<ResolvedItem[]> {
  // Logic to map DOM extracted IDs to ProjectV2Item Node IDs
  // via GET_PROJECT_ITEMS_FOR_RESOLUTION query
}

Sources: src/entries/background/helpers.ts:684-700, src/lib/graphql/queries.ts:135-155

Security & Privacy

• No Backend: All logic runs locally; no data is sent to external servers.
• PAT Storage: The Personal Access Token is stored using the browser.storage API and is only sent to api.github.com.
• Isolation: UI components are injected into a Shadow DOM to ensure they do not interfere with GitHub's native scripts.

Sources: README.md:144-150, wxt.config.ts:98-105

Conclusion

Refined GitHub Projects serves as a power-user layer for GitHub Projects V2, filling gaps in bulk processing and sprint automation. Its architecture prioritizes safety through sequential background execution and utilizes a robust GraphQL-based resolution system to maintain sync between the browser DOM and GitHub's data models.

Sources: README.md:46-55, src/entries/background/helpers.ts:800-820