[OAS-2] Implement hash-based auth.json change detection to optimize secret syncing

[activadee]

Problem Statement

Currently, the plugin syncs secrets to GitHub on every file change event for auth.json, regardless of whether the actual authentication content has changed. This can lead to unnecessary API calls and GitHub secret updates when only metadata or timestamps are updated.

The feature request is to implement hash-based change detection that compares the hash of the current auth.json against a stored hash in the configuration. Only when the hash differs should the plugin sync secrets to repositories.

Current Behavior

• File: lib/watcher.ts (lines 27-41)
• The watcher reads the entire auth.json file on each change event
• String comparison (content === lastContent) detects changes
• Every difference triggers a sync to all configured repositories via gh secret set
• No persistent state tracking of authentication state

Proposed Solution

Implement hash-based change detection by:

1. Store auth.json hash in configuration (lib/config.ts):

   • Add optional authFileHash?: string field to AuthSyncConfig interface in lib/types.ts
   • Load existing hash from config file on startup
   • Persist updated hash back to config file when auth.json changes

2. Update file watcher logic (lib/watcher.ts):

   • Compare SHA-256 hash of current auth.json against stored hash
   • Only trigger sync callback if hashes differ
   • Handle hash computation errors gracefully

3. Update plugin entry point (index.ts):

   • On first sync, compute and store the hash in config
   • Subsequent syncs only occur if hash changes
   • Preserve backward compatibility (if no stored hash, perform sync on first run)

4. Update configuration persistence (lib/config.ts):

   • Add saveConfig() function to write config back to disk (JSON format)
   • Update hash in memory and on disk after successful sync

Implementation Details

New Dependencies

• Use Node.js built-in crypto module for SHA-256 hashing (no new npm dependencies needed)

Type Changes (lib/types.ts)

// Add optional field to AuthSyncConfig interface
authFileHash?: string

Watcher Changes (lib/watcher.ts)

• Compute hash on file read before parsing JSON
• Add hash comparison logic before calling onCredentialsChange
• Return both credentials and hash from handleChange

Configuration Changes (lib/config.ts)

• Add saveConfig(configPath: string, config: AuthSyncConfig): Promise<void> function
• Update type imports from lib/types.ts

Plugin Changes (index.ts)

• Store initial hash after first sync
• Update hash whenever credentials change and sync succeeds

Technical Specifications

• Hash Algorithm: SHA-256 (via Node.js crypto.createHash())
• Hash Format: Hexadecimal string
• Config File Format: Keep existing JSON structure, add optional authFileHash field
• Backward Compatibility: If no authFileHash in config, treat as first run and perform sync
• Error Handling: If hash computation fails, log error and fall back to string comparison

Acceptance Criteria

Functional Requirements

• Hash of auth.json is computed using SHA-256 algorithm
• Hash is stored in the configuration file (alongside existing settings)
• On each file watch event, current hash is compared against stored hash
• Sync to repositories only occurs when hash differs from stored value
• Hash is updated in config file after successful sync
• Initial sync on first run (no stored hash) works correctly
• Backward compatibility: existing configs without authFileHash field work as expected

Edge Cases

• When auth.json doesn't exist, watcher handles gracefully
• When auth.json is corrupted or unreadable, error is logged and fallback occurs
• When config file can't be written, warning is shown but sync still proceeds
• Multiple rapid file changes are debounced correctly (existing 1000ms debounce preserved)

Testing (Implementation Required)

• Unit tests for hash computation function
• Unit tests for hash comparison logic in watcher
• Unit tests for config save/load with hash field
• Integration test: verify sync occurs on hash change
• Integration test: verify sync does NOT occur on content-identical write
• Integration test: verify first run (no existing hash) syncs correctly
• Test backward compatibility: config without authFileHash field loads correctly

Code Quality

• TypeScript strict mode: no any types, all types properly declared
• No use of @ts-ignore or as any suppressions
• Follows existing code patterns in lib/watcher.ts, lib/config.ts
• Maintains existing function signatures where possible
• New functions have JSDoc comments

Documentation

• Update README.md with note about hash-based optimization (optional, mention reduced API calls)
• Code comments explain hash comparison logic in watcher

Files to Modify

• lib/types.ts — Add authFileHash?: string to AuthSyncConfig interface
• lib/watcher.ts — Implement hash comparison in file change handler
• lib/config.ts — Add saveConfig() function for persisting hash
• index.ts — Store and update hash on sync
• (Optional) README.md — Brief mention of hash-based change detection

Related Issues/PRs

Implements optimization requested to reduce unnecessary GitHub API calls and secret updates.