refactor: split augmentation god file and dedupe scraper helpers

Split the 1457-line augmentation.service.ts into focused modules:
- platform-linking.service.ts: URL parsing, scrapers, link* functions
- augmentation-photo.service.ts: photo paths and platform photo fetching
- provider-mapping.service.ts: provider mapping CRUD

Extracted shared utilities and removed duplication:
- fetchHtml utility replaces two hand-rolled https.get redirect blocks
- normalizePhotoUrl utility consolidates URL normalization across
  augmentation-photo, platform-linking, and multi-platform-comparison
- ensureAncestryLoggedIn and extractAncestryPhotoFromPage helpers
  dedupe Ancestry login flow and srcset parsing
- isPlaceholderImage from base.scraper.ts replaces inline checks

Fixed isLegacyFormat type guard that could crash on string/null input.
Removed dead linkFamilySearch function and its only-caller helper.

Author: atomantic

.changelog/NEXT.md

@@ -11,6 +11,9 @@
 
 ## Changed
 
+- Split 1457-line `augmentation.service.ts` god file into focused services: `platform-linking.service.ts` (URL parsing, scrapers, link* functions), `augmentation-photo.service.ts` (photo paths, fetch-from-platform), `provider-mapping.service.ts` (provider mapping CRUD)
+- Extracted shared `fetchHtml` and `normalizePhotoUrl` utilities; consolidated duplicate `normalizePhotoUrl` from `multi-platform-comparison.service.ts`
+- Extracted `ensureAncestryLoggedIn` and `extractAncestryPhotoFromPage` helpers to dedupe Ancestry login + srcset logic
 - Renamed `coverage_gap` audit check to `unlinked_provider` for clarity
 - Split provider linkage check into primary (FamilySearch, Ancestry) at `info` severity and optional (WikiTree, 23andMe) at `hint` severity
 - Removed `unlinked_provider` from default enabled checks (opt-in only)
@@ -22,5 +25,6 @@
 ## Fixed
 
 - Platform comparison now treats equivalent date formats as matches (e.g., "1979-07-31" vs "31 JUL 1979")
+- `isLegacyFormat` augmentation type guard no longer crashes on string/null input
 
 ## Removed

PLAN.md

@@ -441,7 +441,7 @@ Summary: 105 findings across 60+ files. 1 shared utility to extract (SSE Manager
 
 ### Architecture & SOLID
 Architecture findings are tracked but not auto-remediated (all Complex, high risk of regression):
-- [ ] **[HIGH]** `server/src/services/augmentation.service.ts` — 1457-line god file, 5 responsibilities. (Complex)
+- [x] ~~**[HIGH]** `server/src/services/augmentation.service.ts` — 1457-line god file, 5 responsibilities. (Complex)~~ (Split into: core CRUD in augmentation.service.ts, platform-linking.service.ts, augmentation-photo.service.ts, provider-mapping.service.ts)
 - [ ] **[HIGH]** `server/src/services/multi-platform-comparison.service.ts` — 1095-line god file. (Complex)
 - [ ] **[HIGH]** `server/src/services/favorites.service.ts` — 883-line god file. (Complex)
 - [ ] **[HIGH]** `server/src/services/database.service.ts` — 1073-line god file. (Complex)

server/src/routes/augmentation.routes.ts

@@ -3,6 +3,16 @@ import fs from 'fs';
 import path from 'path';
 import type { ProviderPersonMapping, PlatformType } from '@fsf/shared';
 import { augmentationService } from '../services/augmentation.service.js';
+import { linkWikipedia, linkAncestry, linkWikiTree, linkLinkedIn } from '../services/platform-linking.service.js';
+import {
+  getWikiPhotoPath, hasWikiPhoto,
+  getAncestryPhotoPath, hasAncestryPhoto,
+  getWikiTreePhotoPath, hasWikiTreePhoto,
+  getFamilySearchPhotoPath, hasFamilySearchPhoto,
+  getLinkedInPhotoPath, hasLinkedInPhoto,
+  fetchPhotoFromPlatform,
+} from '../services/augmentation-photo.service.js';
+import { getProviderMappings, addProviderMapping, removeProviderMapping } from '../services/provider-mapping.service.js';
 import { logger } from '../lib/logger.js';
 import { sanitizePersonId, isValidUrl } from '../utils/validation.js';
 import { PHOTOS_DIR } from '../utils/paths.js';
@@ -102,7 +112,7 @@ router.get('/:personId', async (req: Request, res: Response) => {
 });
 
 // Link a Wikipedia article to a person
-router.post('/:personId/wikipedia', linkPlatform('wikipedia.org', 'Wikipedia', (id, url) => augmentationService.linkWikipedia(id, url)));
+router.post('/:personId/wikipedia', linkPlatform('wikipedia.org', 'Wikipedia', (id, url) => linkWikipedia(id, url)));
 
 // Update custom augmentation data
 router.put('/:personId', async (req: Request, res: Response) => {
@@ -130,43 +140,43 @@ router.put('/:personId', async (req: Request, res: Response) => {
 });
 
 // Serve Wikipedia photo
-router.get('/:personId/wiki-photo', servePhoto(id => augmentationService.getWikiPhotoPath(id), 'Wiki'));
+router.get('/:personId/wiki-photo', servePhoto(id => getWikiPhotoPath(id), 'Wiki'));
 
 // Check if wiki photo exists
-router.get('/:personId/wiki-photo/exists', checkPhotoExists(id => augmentationService.hasWikiPhoto(id)));
+router.get('/:personId/wiki-photo/exists', checkPhotoExists(id => hasWikiPhoto(id)));
 
 // Link an Ancestry profile to a person
-router.post('/:personId/ancestry', linkPlatform('ancestry.com', 'Ancestry', (id, url) => augmentationService.linkAncestry(id, url)));
+router.post('/:personId/ancestry', linkPlatform('ancestry.com', 'Ancestry', (id, url) => linkAncestry(id, url)));
 
 // Serve Ancestry photo
-router.get('/:personId/ancestry-photo', servePhoto(id => augmentationService.getAncestryPhotoPath(id), 'Ancestry'));
+router.get('/:personId/ancestry-photo', servePhoto(id => getAncestryPhotoPath(id), 'Ancestry'));
 
 // Check if ancestry photo exists
-router.get('/:personId/ancestry-photo/exists', checkPhotoExists(id => augmentationService.hasAncestryPhoto(id)));
+router.get('/:personId/ancestry-photo/exists', checkPhotoExists(id => hasAncestryPhoto(id)));
 
 // Link a WikiTree profile to a person
-router.post('/:personId/wikitree', linkPlatform('wikitree.com', 'WikiTree', (id, url) => augmentationService.linkWikiTree(id, url)));
+router.post('/:personId/wikitree', linkPlatform('wikitree.com', 'WikiTree', (id, url) => linkWikiTree(id, url)));
 
 // Serve WikiTree photo
-router.get('/:personId/wikitree-photo', servePhoto(id => augmentationService.getWikiTreePhotoPath(id), 'WikiTree'));
+router.get('/:personId/wikitree-photo', servePhoto(id => getWikiTreePhotoPath(id), 'WikiTree'));
 
 // Check if wikitree photo exists
-router.get('/:personId/wikitree-photo/exists', checkPhotoExists(id => augmentationService.hasWikiTreePhoto(id)));
+router.get('/:personId/wikitree-photo/exists', checkPhotoExists(id => hasWikiTreePhoto(id)));
 
 // Serve FamilySearch photo
-router.get('/:personId/familysearch-photo', servePhoto(id => augmentationService.getFamilySearchPhotoPath(id), 'FamilySearch'));
+router.get('/:personId/familysearch-photo', servePhoto(id => getFamilySearchPhotoPath(id), 'FamilySearch'));
 
 // Check if FamilySearch photo exists
-router.get('/:personId/familysearch-photo/exists', checkPhotoExists(id => augmentationService.hasFamilySearchPhoto(id)));
+router.get('/:personId/familysearch-photo/exists', checkPhotoExists(id => hasFamilySearchPhoto(id)));
 
 // Link a LinkedIn profile to a person
-router.post('/:personId/linkedin', linkPlatform('linkedin.com', 'LinkedIn', (id, url) => augmentationService.linkLinkedIn(id, url)));
+router.post('/:personId/linkedin', linkPlatform('linkedin.com', 'LinkedIn', (id, url) => linkLinkedIn(id, url)));
 
 // Serve LinkedIn photo
-router.get('/:personId/linkedin-photo', servePhoto(id => augmentationService.getLinkedInPhotoPath(id), 'LinkedIn'));
+router.get('/:personId/linkedin-photo', servePhoto(id => getLinkedInPhotoPath(id), 'LinkedIn'));
 
 // Check if LinkedIn photo exists
-router.get('/:personId/linkedin-photo/exists', checkPhotoExists(id => augmentationService.hasLinkedInPhoto(id)));
+router.get('/:personId/linkedin-photo/exists', checkPhotoExists(id => hasLinkedInPhoto(id)));
 
 // Fetch and download photo from a linked platform
 router.post('/:personId/fetch-photo/:platform', async (req: Request, res: Response) => {
@@ -179,7 +189,7 @@ router.post('/:personId/fetch-photo/:platform', async (req: Request, res: Respon
     return;
   }
 
-  const data = await augmentationService.fetchPhotoFromPlatform(personId, platform as any).catch(err => {
+  const data = await fetchPhotoFromPlatform(personId, platform as any).catch(err => {
     logger.error('augment', `Error fetching photo from ${platform}: ${err.message}`);
     res.status(500).json({ success: false, error: err.message });
     return null;
@@ -193,7 +203,7 @@ router.post('/:personId/fetch-photo/:platform', async (req: Request, res: Respon
 // Get all provider mappings for a person
 router.get('/:personId/provider-links', (req: Request, res: Response) => {
   const personId = sanitizePersonId(req.params.personId);
-  const mappings = augmentationService.getProviderMappings(personId);
+  const mappings = getProviderMappings(personId);
   res.json({ success: true, data: mappings });
 });
 
@@ -226,7 +236,7 @@ router.post('/:personId/provider-link', (req: Request, res: Response) => {
     matchedBy: matchedBy || 'manual',
   };
 
-  const data = augmentationService.addProviderMapping(personId, mapping);
+  const data = addProviderMapping(personId, mapping);
   res.json({ success: true, data });
 });
 
@@ -235,7 +245,7 @@ router.delete('/:personId/provider-link/:providerId', (req: Request, res: Respon
   const personId = sanitizePersonId(req.params.personId);
   const { providerId } = req.params;
 
-  const data = augmentationService.removeProviderMapping(personId, providerId);
+  const data = removeProviderMapping(personId, providerId);
 
   if (!data) {
     res.status(404).json({ success: false, error: 'No augmentation data found' });

server/src/services/ancestry-hints.service.ts

@@ -9,6 +9,7 @@ import type { Page } from 'playwright';
 import type { AncestryHintProgress, AncestryHintResult } from '@fsf/shared';
 import { browserService } from './browser.service.js';
 import { augmentationService } from './augmentation.service.js';
+import { parseAncestryUrl } from './platform-linking.service.js';
 import { providerService } from './provider.service.js';
 import { PROVIDER_DEFAULTS } from './scrapers/base.scraper.js';
 import { logger } from '../lib/logger.js';
@@ -169,7 +170,7 @@ async function processPersonHints(
   }
 
   // Parse the Ancestry URL to get treeId and personId
-  const parsed = augmentationService.parseAncestryUrl(ancestryPlatform.url);
+  const parsed = parseAncestryUrl(ancestryPlatform.url);
   if (!parsed) {
     return {
       personId,
@@ -335,7 +336,7 @@ async function* processPersonHintsWithProgress(
   }
 
   // Parse the Ancestry URL
-  const parsed = augmentationService.parseAncestryUrl(ancestryPlatform.url);
+  const parsed = parseAncestryUrl(ancestryPlatform.url);
   if (!parsed) {
     tracker.finish();
     yield {

server/src/services/ancestry-tree.service.ts

@@ -6,7 +6,7 @@ import type {
   Person
 } from '@fsf/shared';
 import { databaseService } from './database.service.js';
-import { augmentationService } from './augmentation.service.js';
+import { hasAncestryPhoto, hasWikiTreePhoto, hasWikiPhoto } from './augmentation-photo.service.js';
 import { scraperService } from './scraper.service.js';
 import { logger } from '../lib/logger.js';
 
@@ -16,17 +16,17 @@ import { logger } from '../lib/logger.js';
  */
 function resolvePhotoUrl(personId: string): string | undefined {
   // Try Ancestry photo first (highest quality usually)
-  if (augmentationService.hasAncestryPhoto(personId)) {
+  if (hasAncestryPhoto(personId)) {
     return `/api/augment/${personId}/ancestry-photo`;
   }
 
   // Try WikiTree photo
-  if (augmentationService.hasWikiTreePhoto(personId)) {
+  if (hasWikiTreePhoto(personId)) {
     return `/api/augment/${personId}/wikitree-photo`;
   }
 
   // Try Wikipedia photo (via augmentation)
-  if (augmentationService.hasWikiPhoto(personId)) {
+  if (hasWikiPhoto(personId)) {
     return `/api/augment/${personId}/wiki-photo`;
   }
 

server/src/services/ancestry-update.service.ts

@@ -9,6 +9,7 @@ import type { AncestryUpdateProgress } from '@fsf/shared';
 import { sqliteService } from '../db/sqlite.service.js';
 import { idMappingService } from './id-mapping.service.js';
 import { augmentationService } from './augmentation.service.js';
+import { parseAncestryUrl } from './platform-linking.service.js';
 import { ancestryHintsService } from './ancestry-hints.service.js';
 import { providerService } from './provider.service.js';
 import { browserService } from './browser.service.js';
@@ -101,7 +102,7 @@ function getAncestryLink(personId: string): { url: string; treeId: string; ances
 
   if (!ancestryPlatform?.url) return null;
 
-  const parsed = augmentationService.parseAncestryUrl(ancestryPlatform.url);
+  const parsed = parseAncestryUrl(ancestryPlatform.url);
   if (!parsed) return null;
 
   return {

server/src/services/ancestry-upload.service.ts

@@ -10,6 +10,7 @@ import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { browserService } from './browser.service.js';
 import { augmentationService } from './augmentation.service.js';
+import { parseAncestryUrl } from './platform-linking.service.js';
 import { idMappingService } from './id-mapping.service.js';
 import { credentialsService } from './credentials.service.js';
 import { personService } from './person.service.js';
@@ -26,7 +27,7 @@ function getAncestryIds(canonicalId: string): { treeId: string; ancestryPersonId
   const augmentation = augmentationService.getAugmentation(canonicalId);
   const ancestryPlatform = augmentation?.platforms?.find(p => p.platform === 'ancestry');
   if (!ancestryPlatform?.url) return null;
-  return augmentationService.parseAncestryUrl(ancestryPlatform.url);
+  return parseAncestryUrl(ancestryPlatform.url);
 }
 
 /**