attribution links and many other things

Author: ndbroadbent

src/cli/args.ts

@@ -22,6 +22,7 @@ export interface CLIArgs {
   skipPixabay: boolean
   skipWikipedia: boolean
   skipGooglePlaces: boolean
+  mediaLibraryPath: string | undefined
   quiet: boolean
   verbose: boolean
   dryRun: boolean
@@ -151,6 +152,10 @@ function parseCommaSeparated(value: unknown): string[] {
     .filter(Boolean)
 }
 
+function parseOptionalString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined
+}
+
 function parseConfigAction(action: string | undefined): 'list' | 'set' | 'unset' {
   if (action === 'set' || action === 'unset') {
     return action
@@ -173,30 +178,30 @@ function buildCLIArgs(commandName: string, input: string, opts: Record<string, u
     skipPixabay: opts.skipPixabay === true,
     skipWikipedia: opts.skipWikipedia === true,
     skipGooglePlaces: opts.skipGooglePlaces === true,
+    mediaLibraryPath: parseOptionalString(opts.mediaLibraryPath),
     quiet: opts.quiet === true,
     verbose: opts.verbose === true,
     dryRun: opts.dryRun === true,
     debug: opts.debug === true,
     maxResults: Number.parseInt(String(opts.maxResults ?? '10'), 10),
     maxMessages: opts.maxMessages ? Number.parseInt(String(opts.maxMessages), 10) : undefined,
     method: parseMethod(opts.method),
-    jsonOutput:
-      opts.json === true ? 'stdout' : typeof opts.json === 'string' ? opts.json : undefined,
-    homeCountry: typeof opts.homeCountry === 'string' ? opts.homeCountry : undefined,
-    timezone: typeof opts.timezone === 'string' ? opts.timezone : undefined,
+    jsonOutput: opts.json === true ? 'stdout' : parseOptionalString(opts.json),
+    homeCountry: parseOptionalString(opts.homeCountry),
+    timezone: parseOptionalString(opts.timezone),
     scrapeConcurrency: Number.parseInt(String(opts.concurrency ?? '5'), 10),
     scrapeTimeout: Number.parseInt(String(opts.timeout ?? '4000'), 10),
     noCache: opts.cache === false,
-    cacheDir: typeof opts.cacheDir === 'string' ? opts.cacheDir : undefined,
-    configFile: typeof opts.configFile === 'string' ? opts.configFile : undefined,
+    cacheDir: parseOptionalString(opts.cacheDir),
+    configFile: parseOptionalString(opts.configFile),
     showAll: opts.all === true,
 
     // Common export settings
     exportCategories: parseCommaSeparated(opts.exportCategories),
     exportCountries: parseCommaSeparated(opts.exportCountries),
     exportFrom: parseCommaSeparated(opts.exportFrom),
-    exportStartDate: typeof opts.exportStartDate === 'string' ? opts.exportStartDate : undefined,
-    exportEndDate: typeof opts.exportEndDate === 'string' ? opts.exportEndDate : undefined,
+    exportStartDate: parseOptionalString(opts.exportStartDate),
+    exportEndDate: parseOptionalString(opts.exportEndDate),
     exportMinScore: parseOptionalNumber(opts.exportMinScore),
     exportOnlyLocations: opts.exportOnlyLocations === true,
     exportOnlyGeneric: opts.exportOnlyGeneric === true,
@@ -211,25 +216,25 @@ function buildCLIArgs(commandName: string, input: string, opts: Record<string, u
       opts.pdfGroupByCategory,
       opts.pdfNoGroupByCategory
     ),
-    pdfPageSize: typeof opts.pdfPageSize === 'string' ? opts.pdfPageSize : undefined,
-    pdfTitle: typeof opts.pdfTitle === 'string' ? opts.pdfTitle : undefined,
-    pdfSubtitle: typeof opts.pdfSubtitle === 'string' ? opts.pdfSubtitle : undefined,
+    pdfPageSize: parseOptionalString(opts.pdfPageSize),
+    pdfTitle: parseOptionalString(opts.pdfTitle),
+    pdfSubtitle: parseOptionalString(opts.pdfSubtitle),
     pdfCategories: parseCommaSeparated(opts.pdfCategories),
     pdfCountries: parseCommaSeparated(opts.pdfCountries),
     pdfFrom: parseCommaSeparated(opts.pdfFrom),
-    pdfStartDate: typeof opts.pdfStartDate === 'string' ? opts.pdfStartDate : undefined,
-    pdfEndDate: typeof opts.pdfEndDate === 'string' ? opts.pdfEndDate : undefined,
+    pdfStartDate: parseOptionalString(opts.pdfStartDate),
+    pdfEndDate: parseOptionalString(opts.pdfEndDate),
     pdfMinScore: parseOptionalNumber(opts.pdfMinScore),
     pdfOnlyLocations: opts.pdfOnlyLocations === true,
     pdfOnlyGeneric: opts.pdfOnlyGeneric === true,
     pdfMaxActivities: Number.parseInt(String(opts.pdfMaxActivities ?? '0'), 10),
     pdfSort: parseSortOrder(opts.pdfSort),
 
     // Map-specific settings
-    mapDefaultStyle: typeof opts.mapDefaultStyle === 'string' ? opts.mapDefaultStyle : undefined,
+    mapDefaultStyle: parseOptionalString(opts.mapDefaultStyle),
 
     // Export subcommand settings
-    exportOutput: typeof opts.output === 'string' ? opts.output : undefined,
+    exportOutput: parseOptionalString(opts.output),
     exportFormat: undefined,
 
     configAction: 'list',

src/cli/commands.ts

@@ -108,6 +108,10 @@ function addPipelineOptions(cmd: Command): Command {
     .option('--min-confidence <num>', 'Minimum confidence threshold', '0.5')
     .option('--skip-geocoding', 'Skip geocoding step')
     .option('--images', 'Fetch images for activities (slower, uses external APIs)')
+    .option(
+      '--media-library-path <path>',
+      'Local path to media library images (development/offline)'
+    )
     .option('--map-default-style <style>', 'Default map tile style (e.g. osm, satellite, terrain)')
     .option('-m, --max-messages <num>', 'Max messages to process (for testing)')
     .option('--dry-run', 'Show stats without API calls')
@@ -318,6 +322,10 @@ export function createProgram(): Command {
     .option('--skip-pixabay', 'Skip Pixabay image search')
     .option('--skip-wikipedia', 'Skip Wikipedia image lookup')
     .option('--skip-google-places', 'Skip Google Places photos')
+    .option(
+      '--media-library-path <path>',
+      'Local path to media library images (development/offline)'
+    )
     .option('-n, --max-results <num>', 'Max results to display', '10')
     .option('-a, --all', 'Show all activities with images')
 

src/cli/commands/fetch-image-urls.ts

@@ -18,15 +18,19 @@ import type { Logger } from '../logger'
 import { stepFetchImageUrls } from '../steps/fetch-image-urls'
 import { StepRunner } from '../steps/runner'
 
-interface FetchImagesOutput {
+interface FetchImagesStats {
   activitiesProcessed: number
   imagesFound: number
+  fromMediaLibrary: number
   fromCdn: number
   fromWikipedia: number
   fromPixabay: number
   fromGooglePlaces: number
   fromUserUpload: number
   failed: number
+}
+
+interface FetchImagesOutput extends FetchImagesStats {
   activities: Array<{
     activityId: string
     activity: string
@@ -38,6 +42,19 @@ interface FetchImagesOutput {
   }>
 }
 
+function logStatsSummary(stats: FetchImagesStats, logger: Logger): void {
+  logger.log('\n📊 Image Fetch Results')
+  logger.log(`   Processed: ${stats.activitiesProcessed}`)
+  logger.log(`   Found: ${stats.imagesFound}`)
+  if (stats.fromMediaLibrary > 0) logger.log(`   From Media Library: ${stats.fromMediaLibrary}`)
+  if (stats.fromCdn > 0) logger.log(`   From CDN: ${stats.fromCdn}`)
+  if (stats.fromUserUpload > 0) logger.log(`   From user uploads: ${stats.fromUserUpload}`)
+  if (stats.fromWikipedia > 0) logger.log(`   From Wikipedia: ${stats.fromWikipedia}`)
+  if (stats.fromPixabay > 0) logger.log(`   From Pixabay: ${stats.fromPixabay}`)
+  if (stats.fromGooglePlaces > 0) logger.log(`   From Google Places: ${stats.fromGooglePlaces}`)
+  if (stats.failed > 0) logger.log(`   Not found: ${stats.failed}`)
+}
+
 export async function cmdFetchImageUrls(args: CLIArgs, logger: Logger): Promise<void> {
   const { ctx, config } = await initCommandContext('Fetch Image URLs', args, logger)
 
@@ -68,27 +85,18 @@ export async function cmdFetchImageUrls(args: CLIArgs, logger: Logger): Promise<
   }
 
   // Run fetch-image-urls step
+  // Media library path can come from CLI arg or config
+  const mediaLibraryPath = args.mediaLibraryPath ?? config?.mediaLibraryPath
   const fetchResult = await stepFetchImageUrls(ctx, geocodedActivities, {
     skipCdn: args.skipCdn,
     skipPixabay: args.skipPixabay,
     skipWikipedia: args.skipWikipedia,
-    skipGooglePlaces: args.skipGooglePlaces
+    skipGooglePlaces: args.skipGooglePlaces,
+    mediaLibraryPath
   })
 
   // Summary
-  logger.log('\n📊 Image Fetch Results')
-  logger.log(`   Processed: ${fetchResult.stats.activitiesProcessed}`)
-  logger.log(`   Found: ${fetchResult.stats.imagesFound}`)
-  if (fetchResult.stats.fromCdn > 0) logger.log(`   From CDN: ${fetchResult.stats.fromCdn}`)
-  if (fetchResult.stats.fromUserUpload > 0)
-    logger.log(`   From user uploads: ${fetchResult.stats.fromUserUpload}`)
-  if (fetchResult.stats.fromWikipedia > 0)
-    logger.log(`   From Wikipedia: ${fetchResult.stats.fromWikipedia}`)
-  if (fetchResult.stats.fromPixabay > 0)
-    logger.log(`   From Pixabay: ${fetchResult.stats.fromPixabay}`)
-  if (fetchResult.stats.fromGooglePlaces > 0)
-    logger.log(`   From Google Places: ${fetchResult.stats.fromGooglePlaces}`)
-  if (fetchResult.stats.failed > 0) logger.log(`   Not found: ${fetchResult.stats.failed}`)
+  logStatsSummary(fetchResult.stats, logger)
 
   const output: FetchImagesOutput = {
     ...fetchResult.stats,

src/cli/config.ts

@@ -26,6 +26,8 @@ export interface Config {
   outputDir?: string | undefined
   /** Export formats (csv,excel,json,map,pdf) */
   formats?: string[] | undefined
+  /** Local path to media library images (for development/offline use) */
+  mediaLibraryPath?: string | undefined
 
   // === Common export settings (apply to ALL formats) ===
   /** Filter ALL exports by categories */
@@ -102,6 +104,7 @@ const STRING_KEYS: ConfigKey[] = [
   'timezone',
   'cacheDir',
   'outputDir',
+  'mediaLibraryPath',
   // Common export
   'exportStartDate',
   'exportEndDate',
@@ -159,6 +162,7 @@ const CONFIG_DESCRIPTIONS: Record<ConfigKey, string> = {
   fetchImages: 'Fetch images by default (default: false)',
   formats: 'Export formats (default: csv,excel,json,map,pdf)',
   homeCountry: 'Your home country for location context (default: detected from IP)',
+  mediaLibraryPath: 'Local path to media library images (for development/offline use)',
   outputDir: 'Output directory for exports (default: ./output)',
   timezone: 'Your timezone (e.g. Pacific/Auckland) (default: detected from system)',
 

src/cli/steps/fetch-image-urls.ts

@@ -25,6 +25,7 @@ const DEFAULT_CONCURRENCY = 10
 interface FetchImagesStats {
   readonly activitiesProcessed: number
   readonly imagesFound: number
+  readonly fromMediaLibrary: number
   readonly fromCdn: number
   readonly fromGooglePlaces: number
   readonly fromWikipedia: number
@@ -33,6 +34,19 @@ interface FetchImagesStats {
   readonly failed: number
 }
 
+/** Mutable version for accumulation */
+interface MutableStats {
+  activitiesProcessed: number
+  imagesFound: number
+  fromMediaLibrary: number
+  fromCdn: number
+  fromGooglePlaces: number
+  fromWikipedia: number
+  fromPixabay: number
+  fromUserUpload: number
+  failed: number
+}
+
 /**
  * Result of the fetch images step.
  */
@@ -63,37 +77,23 @@ interface FetchImagesOptions {
   readonly googlePlacesApiKey?: string | undefined
   /** Number of concurrent image fetches (default 10) */
   readonly concurrency?: number | undefined
+  /** Local path to media library images (for development/offline use) */
+  readonly mediaLibraryPath?: string | undefined
 }
 
 /** Serializable version of image results for caching */
 interface CachedImageData {
   readonly entries: Array<[string, ImageResult | null]>
 }
 
-/**
- * Count source from image result.
- */
-function countSource(result: ImageResult): keyof Omit<FetchImagesStats, 'activitiesProcessed'> {
-  const sourceMap: Record<
-    ImageResult['source'],
-    keyof Omit<FetchImagesStats, 'activitiesProcessed'>
-  > = {
-    cdn: 'fromCdn',
-    google_places: 'fromGooglePlaces',
-    wikipedia: 'fromWikipedia',
-    pixabay: 'fromPixabay',
-    user_upload: 'fromUserUpload'
-  }
-  return sourceMap[result.source]
-}
-
 /**
  * Calculate stats from image results.
  */
 function calculateStats(images: Map<string, ImageResult | null>): FetchImagesStats {
-  const stats = {
+  const stats: MutableStats = {
     activitiesProcessed: images.size,
     imagesFound: 0,
+    fromMediaLibrary: 0,
     fromCdn: 0,
     fromGooglePlaces: 0,
     fromWikipedia: 0,
@@ -105,7 +105,7 @@ function calculateStats(images: Map<string, ImageResult | null>): FetchImagesSta
   for (const result of images.values()) {
     if (result) {
       stats.imagesFound++
-      stats[countSource(result)]++
+      incrementSourceCount(stats, result.source)
     } else {
       stats.failed++
     }
@@ -114,11 +114,38 @@ function calculateStats(images: Map<string, ImageResult | null>): FetchImagesSta
   return stats
 }
 
+/**
+ * Increment the appropriate source count based on image source.
+ */
+function incrementSourceCount(stats: MutableStats, source: ImageResult['source']): void {
+  switch (source) {
+    case 'media_library':
+      stats.fromMediaLibrary++
+      break
+    case 'cdn':
+      stats.fromCdn++
+      break
+    case 'google_places':
+      stats.fromGooglePlaces++
+      break
+    case 'wikipedia':
+      stats.fromWikipedia++
+      break
+    case 'pixabay':
+      stats.fromPixabay++
+      break
+    case 'user_upload':
+      stats.fromUserUpload++
+      break
+  }
+}
+
 /**
  * Log stats about fetched images.
  */
 function logStats(stats: FetchImagesStats, logger: PipelineContext['logger']): void {
   logger.log(`   ✓ ${stats.imagesFound}/${stats.activitiesProcessed} images found`)
+  if (stats.fromMediaLibrary > 0) logger.log(`   📸 ${stats.fromMediaLibrary} from Media Library`)
   if (stats.fromCdn > 0) logger.log(`   📦 ${stats.fromCdn} from CDN`)
   if (stats.fromUserUpload > 0) logger.log(`   📤 ${stats.fromUserUpload} from user uploads`)
   if (stats.fromWikipedia > 0) logger.log(`   📚 ${stats.fromWikipedia} from Wikipedia`)
@@ -160,6 +187,7 @@ export async function stepFetchImageUrls(
     const stats: FetchImagesStats = {
       activitiesProcessed: 0,
       imagesFound: 0,
+      fromMediaLibrary: 0,
       fromCdn: 0,
       fromGooglePlaces: 0,
       fromWikipedia: 0,
@@ -185,7 +213,8 @@ export async function stepFetchImageUrls(
     googlePlacesApiKey:
       options?.googlePlacesApiKey ??
       process.env.GOOGLE_MAPS_API_KEY ??
-      process.env.GOOGLE_MAPS_API_KEY
+      process.env.GOOGLE_MAPS_API_KEY,
+    mediaLibraryPath: options?.mediaLibraryPath
   }
 
   // Log what sources are available

src/cli/steps/runner.ts

@@ -192,12 +192,16 @@ export class StepRunner {
     // Dependency: geocode
     const { activities } = await this.run('geocode')
 
+    // Media library path can come from CLI arg or config
+    const mediaLibraryPath = this.args.mediaLibraryPath ?? this.config?.mediaLibraryPath
+
     const { stepFetchImageUrls } = await import('./fetch-image-urls')
     const result = await stepFetchImageUrls(this.ctx, activities, {
       skipCdn: this.args.skipCdn,
       skipPixabay: this.args.skipPixabay,
       skipWikipedia: this.args.skipWikipedia,
-      skipGooglePlaces: this.args.skipGooglePlaces
+      skipGooglePlaces: this.args.skipGooglePlaces,
+      mediaLibraryPath
     })
     return { images: result.images }
   }