@yuiseki/gyazocli 0.1.1 → 0.3.0

package/README.md

@@ -86,6 +86,67 @@ Environment variables:
 - `GYAZO_CACHE_DIR`: cache location
 - `GYAZO_API_ORIGIN` / `GYAZO_UPLOAD_ORIGIN` / `GYAZO_WEB_ORIGIN`: override the endpoints (used by the test suite)
 
+## MCP server
+
+`gyazo --mcp-server` runs the CLI as a Model Context Protocol server over
+stdio, so an MCP client can search your captures. `--mcp`, `mcp-server` and
+`mcp` start the same thing.
+
+```bash
+gyazo --mcp-server
+```
+
+It needs an access token before it starts, from `gyazo config set token` or
+from `GYAZO_ACCESS_TOKEN` in the client's environment. stdout carries only
+JSON-RPC; anything meant for a human goes to stderr.
+
+Configured in a client:
+
+```json
+{
+  "mcpServers": {
+    "gyazo": {
+      "command": "npx",
+      "args": ["-y", "@yuiseki/gyazocli", "--mcp-server"],
+      "env": { "GYAZO_ACCESS_TOKEN": "your_access_token" }
+    }
+  }
+}
+```
+
+### Tools
+
+- `gyazo_search`: full-text search over your captures. Arguments: `query`
+  (required, up to 200 characters), `page` (default 1), `per` (default 20,
+  max 100). Search syntax is the same as Gyazo's: `cat`, `title:cat`,
+  `app:"Google Chrome"`, `url:google.com`, `cat since:2024-01-01 until:2024-12-31`.
+- `gyazo_image`: metadata for one capture. Argument: `id_or_url` (required),
+  which accepts a bare 32-character ID, a `https://gyazo.com/<id>` permalink or
+  a direct image URL.
+- `gyazo_latest_image`: metadata for the capture uploaded most recently. No
+  arguments.
+- `gyazo_list`: the captures, newest first, with the same options as
+  `gyazo list`: `page`, `limit`, `date`, `today`, `hour`, `photos`, `uploaded`,
+  `max_pages`, `use_cache`. No arguments means the most recent page.
+- `gyazo_summary`: what a day or a range adds up to, with the same options as
+  `gyazo summary`: `date`, `today`, `limit`, `max_pages`, `use_cache`. No
+  arguments means the week up to yesterday.
+- `gyazo_collection`: a collection and the captures in it. Arguments:
+  `id_or_url` (required) and `sort` (`added`, `created` or `captured`).
+
+All of them are read-only, and all of them return metadata rather than image
+bytes. A capture that carries coordinates gets a `location: {latitude,
+longitude}`, and OCR text is reported wherever the response carries it: URLs, timestamp, OCR text, title, source application and page, and
+location when the capture carries one. Use the URLs in a result to show the
+capture itself. Handing base64 image data to a model turned out not to work
+well in practice, and describing a capture does.
+
+Tool names and arguments follow
+[nota/gyazo-mcp-server](https://github.com/nota/gyazo-mcp-server), so a client
+already configured against that server can point at this one instead. Its
+`gyazo_upload` is deliberately absent: nothing here can write to your Gyazo
+account until there is a reason for it to.
+
 ## Development
 
 ### Build
@@ -101,6 +162,11 @@ npm run build
 npm test
 ```
 
+### Release
+
+Push a `v*` tag and Actions stages the package on npm, where a maintainer
+approves it with 2FA. See [RELEASE.md](RELEASE.md).
+
 ### Link local CLI with npm link
 
 ```bash

package/dist/commands/apps.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAppsCommand = registerAppsCommand;
+const credentials_1 = require("../credentials");
+const dates_1 = require("../dates");
+const options_1 = require("../options");
+const memory_1 = require("../services/memory");
+const analytics_1 = require("../services/analytics");
+function registerAppsCommand(program) {
+    program
+        .command('apps')
+        .description('Rank metadata app names for a specific date')
+        .option('--date <yyyy|yyyy-mm|yyyy-mm-dd>', 'target date/range')
+        .option('--today', 'target today only (overrides default weekly range)')
+        .option('-l, --limit <number>', 'maximum ranking rows (max: 10)', '10')
+        .option('--max-pages <number>', 'max pages to scan before stopping', '10')
+        .option('-j, --json', 'output as JSON')
+        .option('--no-cache', 'force fetch from API')
+        .action(async (options) => {
+        await (0, credentials_1.ensureAccessToken)();
+        try {
+            const targetDate = (0, dates_1.resolveRankingRangeOption)(options);
+            const requestedLimit = (0, options_1.parsePositiveIntegerOption)(options.limit, '--limit');
+            const limit = Math.min(requestedLimit, 10);
+            const maxPages = (0, options_1.parsePositiveIntegerOption)(options.maxPages, '--max-pages');
+            const useCache = options.cache !== false;
+            let ranking = [];
+            let totalWithApp = 0;
+            let totalImages = 0;
+            if (useCache) {
+                let cacheSummary = (0, analytics_1.buildAppsRankingFromHourlyCache)(targetDate);
+                if (cacheSummary.totalImages === 0) {
+                    await (0, memory_1.warmDateCacheForApps)(targetDate, maxPages, true);
+                    cacheSummary = (0, analytics_1.buildAppsRankingFromHourlyCache)(targetDate);
+                }
+                ranking = cacheSummary.ranking;
+                totalWithApp = cacheSummary.imageCountWithApps;
+                totalImages = cacheSummary.totalImages;
+            }
+            else {
+                const imageIds = await (0, memory_1.warmDateCacheForApps)(targetDate, maxPages, false);
+                ranking = (0, analytics_1.buildAppsRankingFromCache)(imageIds);
+                totalWithApp = ranking.reduce((sum, item) => sum + item.count, 0);
+                totalImages = imageIds.length;
+            }
+            const displayedRanking = ranking.slice(0, limit);
+            if (options.json) {
+                console.log(JSON.stringify({
+                    date: targetDate.dateKey,
+                    image_count: totalImages,
+                    app_image_count: totalWithApp,
+                    total_apps: ranking.length,
+                    ranking: displayedRanking,
+                }, null, 2));
+                return;
+            }
+            if (ranking.length === 0) {
+                console.log(`No app metadata found for ${targetDate.dateKey}.`);
+                return;
+            }
+            console.log(`Apps on ${targetDate.dateKey}`);
+            displayedRanking.forEach((item, index) => {
+                console.log(`${index + 1}. ${item.app}: ${item.count}`);
+            });
+            console.log(`Total images with app metadata: ${totalWithApp}`);
+        }
+        catch (error) {
+            console.error('Error ranking apps:', error.message);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/collection.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCollectionCommand = registerCollectionCommand;
+const credentials_1 = require("../credentials");
+const collections_1 = require("../services/collections");
+function registerCollectionCommand(program) {
+    program
+        .command('collection <collection_id>')
+        .aliases(['col', 'cols', 'collections'])
+        .description('Show a collection and the images in it')
+        .option('-j, --json', 'output as JSON')
+        .option('-A, --anonymous', 'read without an access token, even when one is configured')
+        .option('--sort <added|created|captured>', 'image order (default: added)')
+        .action(async (collectionIdInput, options) => {
+        const collectionId = (0, collections_1.requireCollectionId)(collectionIdInput);
+        const sort = (0, collections_1.parseCollectionSort)(options.sort);
+        // No token is not an error here: public collections read fine anonymously.
+        if (!options.anonymous) {
+            (0, credentials_1.resolveAccessToken)();
+        }
+        try {
+            const { collection, images } = await (0, collections_1.readCollection)(collectionId, {
+                anonymous: Boolean(options.anonymous),
+                sort,
+            });
+            if (options.json) {
+                console.log(JSON.stringify(collection, null, 2));
+                return;
+            }
+            (0, collections_1.printCollectionMarkdown)(collection, images);
+        }
+        catch (error) {
+            if (error?.response?.status === 404) {
+                console.error(`Error: collection ${collectionId} was not found or not public.`);
+                console.error('Hint: a private collection returns the same 404 as one that does not exist.');
+                if (options.anonymous) {
+                    console.error('Hint: you are running with --anonymous. Drop it to use your access token.');
+                }
+                process.exit(1);
+            }
+            console.error('Error getting collection:', error.message);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/config.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerConfigCommand = registerConfigCommand;
+const api_1 = require("../api");
+const credentials_1 = require("../credentials");
+function registerConfigCommand(program) {
+    const configCmd = program.command('config').description('Manage configuration');
+    configCmd
+        .command('set <key> <value>')
+        .description('Set a configuration value')
+        .action((key, value) => {
+        (0, credentials_1.setStoredConfig)(key, value);
+    });
+    configCmd
+        .command('get <key>')
+        .description('Get a configuration value')
+        .option('-j, --json', 'output as JSON')
+        .action(async (key, options) => {
+        if (key === 'me') {
+            await (0, credentials_1.ensureAccessToken)();
+            try {
+                const me = await (0, api_1.getCurrentUser)();
+                if (options.json) {
+                    console.log(JSON.stringify(me, null, 2));
+                    return;
+                }
+                const user = me?.user || {};
+                if (user.uid)
+                    console.log(`UID: ${user.uid}`);
+                if (user.name)
+                    console.log(`Name: ${user.name}`);
+                if (user.email)
+                    console.log(`Email: ${user.email}`);
+                if (typeof user.is_pro === 'boolean')
+                    console.log(`Plan: ${user.is_pro ? 'Pro' : 'Free'}`);
+                if (typeof user.is_team === 'boolean')
+                    console.log(`Team: ${user.is_team ? 'Yes' : 'No'}`);
+                if (user.profile_image)
+                    console.log(`Profile image: ${user.profile_image}`);
+            }
+            catch (error) {
+                console.error('Error getting current user:', error.message);
+                process.exit(1);
+            }
+            return;
+        }
+        const value = (0, credentials_1.getStoredConfig)(key);
+        if (value) {
+            if (key === 'token') {
+                const masked = value.length > 8
+                    ? `${value.substring(0, 4)}...${value.substring(value.length - 4)}`
+                    : '********';
+                console.log(masked);
+            }
+            else {
+                console.log(value);
+            }
+        }
+        else {
+            console.error(`Config key '${key}' not found.`);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/domains.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDomainsCommand = registerDomainsCommand;
+const credentials_1 = require("../credentials");
+const dates_1 = require("../dates");
+const options_1 = require("../options");
+const memory_1 = require("../services/memory");
+const analytics_1 = require("../services/analytics");
+function registerDomainsCommand(program) {
+    program
+        .command('domains')
+        .description('Rank metadata URL domains for a specific date')
+        .option('--date <yyyy|yyyy-mm|yyyy-mm-dd>', 'target date/range')
+        .option('--today', 'target today only (overrides default weekly range)')
+        .option('-l, --limit <number>', 'maximum ranking rows (max: 10)', '10')
+        .option('--max-pages <number>', 'max pages to scan before stopping', '10')
+        .option('-j, --json', 'output as JSON')
+        .option('--no-cache', 'force fetch from API')
+        .action(async (options) => {
+        await (0, credentials_1.ensureAccessToken)();
+        try {
+            const targetDate = (0, dates_1.resolveRankingRangeOption)(options);
+            const requestedLimit = (0, options_1.parsePositiveIntegerOption)(options.limit, '--limit');
+            const limit = Math.min(requestedLimit, 10);
+            const maxPages = (0, options_1.parsePositiveIntegerOption)(options.maxPages, '--max-pages');
+            const useCache = options.cache !== false;
+            let ranking = [];
+            let totalWithDomain = 0;
+            let totalImages = 0;
+            if (useCache) {
+                let cacheSummary = (0, analytics_1.buildDomainsRankingFromHourlyCache)(targetDate);
+                if (cacheSummary.totalImages === 0) {
+                    await (0, memory_1.warmDateCacheForDomains)(targetDate, maxPages, true);
+                    cacheSummary = (0, analytics_1.buildDomainsRankingFromHourlyCache)(targetDate);
+                }
+                ranking = cacheSummary.ranking;
+                totalWithDomain = cacheSummary.imageCountWithDomains;
+                totalImages = cacheSummary.totalImages;
+            }
+            else {
+                const imageIds = await (0, memory_1.warmDateCacheForDomains)(targetDate, maxPages, false);
+                ranking = (0, analytics_1.buildDomainsRankingFromCache)(imageIds);
+                totalWithDomain = ranking.reduce((sum, item) => sum + item.count, 0);
+                totalImages = imageIds.length;
+            }
+            const displayedRanking = ranking.slice(0, limit);
+            if (options.json) {
+                console.log(JSON.stringify({
+                    date: targetDate.dateKey,
+                    image_count: totalImages,
+                    domain_image_count: totalWithDomain,
+                    total_domains: ranking.length,
+                    ranking: displayedRanking,
+                }, null, 2));
+                return;
+            }
+            if (ranking.length === 0) {
+                console.log(`No domain metadata found for ${targetDate.dateKey}.`);
+                return;
+            }
+            console.log(`Domains on ${targetDate.dateKey}`);
+            displayedRanking.forEach((item, index) => {
+                console.log(`${index + 1}. ${item.domain}: ${item.count}`);
+            });
+            console.log(`Total images with domain metadata: ${totalWithDomain}`);
+        }
+        catch (error) {
+            console.error('Error ranking domains:', error.message);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/get.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerGetCommand = registerGetCommand;
+const api_1 = require("../api");
+const storage_1 = require("../storage");
+const credentials_1 = require("../credentials");
+const format_1 = require("../format");
+const memory_1 = require("../services/memory");
+const images_1 = require("../services/images");
+function registerGetCommand(program) {
+    program
+        .command('get <image_id>')
+        .description('Get detailed metadata for an image')
+        .option('-j, --json', 'output as JSON')
+        .option('--ocr', 'output OCR text only')
+        .option('--objects', 'output object annotations only')
+        .option('--no-cache', 'force fetch from API')
+        .action(async (imageId, options) => {
+        await (0, credentials_1.ensureAccessToken)();
+        try {
+            if (options.json && (options.ocr || options.objects)) {
+                console.error('Error: --json cannot be used with --ocr or --objects.');
+                process.exit(1);
+            }
+            if (options.ocr && options.objects) {
+                console.error('Error: --ocr and --objects cannot be used together.');
+                process.exit(1);
+            }
+            imageId = (0, images_1.requireImageId)(imageId);
+            let image = options.cache !== false ? (0, storage_1.loadImageCache)(imageId) : null;
+            if (!image) {
+                image = await (0, api_1.getImageDetail)(imageId);
+                (0, storage_1.saveImageCache)(imageId, image);
+            }
+            const supplemented = (0, memory_1.supplementAltTextFromSearchCache)(image);
+            image = supplemented.image;
+            if (supplemented.supplemented) {
+                (0, storage_1.saveImageCache)(imageId, image);
+            }
+            const ocrDescription = (0, format_1.extractOcrDescription)(image);
+            const objects = (0, format_1.extractObjectAnnotations)(image);
+            if (options.ocr) {
+                if (!ocrDescription) {
+                    console.error('OCR not found for this image.');
+                    process.exit(1);
+                }
+                console.log(ocrDescription);
+                return;
+            }
+            if (options.objects) {
+                if (objects.length === 0) {
+                    console.error('Object annotations not found for this image.');
+                    process.exit(1);
+                }
+                console.log(objects.map(format_1.formatObjectAnnotationLine).join('\n'));
+                return;
+            }
+            if (options.json) {
+                console.log(JSON.stringify(image, null, 2));
+            }
+            else {
+                (0, images_1.printGetMarkdown)(image, ocrDescription, objects);
+            }
+        }
+        catch (error) {
+            console.error('Error getting image:', error.message);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/import.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerImportCommand = registerImportCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const storage_1 = require("../storage");
+function registerImportCommand(program) {
+    program
+        .command('import <type> <dir>')
+        .description('Import legacy data (type: json|hourly)')
+        .action(async (type, dir) => {
+        const sourceDir = path_1.default.resolve(dir);
+        if (!fs_1.default.existsSync(sourceDir)) {
+            console.error(`Error: Source directory ${sourceDir} does not exist.`);
+            process.exit(1);
+        }
+        if (type === 'json') {
+            const targetDir = path_1.default.join((0, storage_1.getCacheDir)(), 'images');
+            console.log(`Importing legacy Gyazo JSON from ${sourceDir}...`);
+            let total = 0;
+            const walk = (d) => {
+                fs_1.default.readdirSync(d, { withFileTypes: true }).forEach(e => {
+                    const p = path_1.default.join(d, e.name);
+                    if (e.isDirectory())
+                        walk(p);
+                    else if (e.name.endsWith('.json')) {
+                        const id = e.name.replace('.json', '');
+                        const p1 = id[0] || '_', p2 = id[1] || '_';
+                        const dest = path_1.default.join(targetDir, p1, p2);
+                        if (!fs_1.default.existsSync(dest))
+                            fs_1.default.mkdirSync(dest, { recursive: true });
+                        fs_1.default.copyFileSync(p, path_1.default.join(dest, e.name));
+                        total++;
+                        if (total % 100 === 0)
+                            process.stdout.write('.');
+                    }
+                });
+            };
+            walk(sourceDir);
+            console.log(`\nImport complete. Copied ${total} files.`);
+        }
+        else if (type === 'hourly') {
+            console.log(`Importing legacy Gyazo hourly data from ${sourceDir}...`);
+            let total = 0;
+            const years = fs_1.default.readdirSync(sourceDir).filter(f => /^[0-9]{4}$/.test(f));
+            for (const y of years) {
+                const months = fs_1.default.readdirSync(path_1.default.join(sourceDir, y)).filter(f => /^[0-9]{2}$/.test(f));
+                for (const m of months) {
+                    const days = fs_1.default.readdirSync(path_1.default.join(sourceDir, y, m)).filter(f => /^[0-9]{2}$/.test(f));
+                    for (const d of days) {
+                        const hours = fs_1.default.readdirSync(path_1.default.join(sourceDir, y, m, d)).filter(f => /^[0-9]{2}$/.test(f));
+                        for (const h of hours) {
+                            const txt = path_1.default.join(sourceDir, y, m, d, h, 'image_ids.txt');
+                            if (fs_1.default.existsSync(txt)) {
+                                const ids = fs_1.default.readFileSync(txt, 'utf-8').split('\n').map(id => id.trim()).filter(id => id.length > 0);
+                                (0, storage_1.saveHourlyCache)(y, m, d, h, ids);
+                                total++;
+                            }
+                        }
+                    }
+                }
+                process.stdout.write('.');
+            }
+            console.log(`\nImport complete. Copied ${total} hourly index files.`);
+        }
+        else {
+            console.error('Error: type must be "json" or "hourly"');
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/list.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerListCommand = registerListCommand;
+const credentials_1 = require("../credentials");
+const dates_1 = require("../dates");
+const options_1 = require("../options");
+const memory_1 = require("../services/memory");
+const images_1 = require("../services/images");
+function registerListCommand(program) {
+    program
+        .command('list')
+        .alias('ls')
+        .description('List recent images')
+        .option('-p, --page <number>', 'page number', '1')
+        .option('-l, --limit <number>', 'items per page', '20')
+        .option('-j, --json', 'output as JSON')
+        .option('-H, --hour <yyyy-mm-dd-hh>', 'target hour')
+        .option('--date <yyyy|yyyy-mm|yyyy-mm-dd>', 'target date/range')
+        .option('--today', 'target today only')
+        .option('--max-pages <number>', 'max pages to scan for --date/--today mode', '100')
+        .option('--photos', 'alias of search "has:location"')
+        .option('--uploaded', 'alias of search "gyazocli_uploads"')
+        .option('--no-cache', 'force fetch from API')
+        .action(async (options) => {
+        await (0, credentials_1.ensureAccessToken)();
+        try {
+            const useCache = options.cache !== false;
+            const page = (0, options_1.parsePositiveIntegerOption)(options.page, '--page');
+            const limit = (0, options_1.parsePositiveIntegerOption)(options.limit, '--limit');
+            const maxPages = (0, options_1.parsePositiveIntegerOption)(options.maxPages, '--max-pages');
+            const hasDateRange = Boolean(options.date || options.today);
+            if (options.photos && options.uploaded) {
+                console.error('Error: --photos and --uploaded cannot be used together.');
+                process.exit(1);
+            }
+            if (options.today && options.date) {
+                console.error('Error: --today and --date cannot be used together.');
+                process.exit(1);
+            }
+            if ((options.photos || options.uploaded) && options.hour) {
+                console.error('Error: --photos/--uploaded and --hour cannot be used together.');
+                process.exit(1);
+            }
+            if (options.hour && hasDateRange) {
+                console.error('Error: --hour and --date/--today cannot be used together.');
+                process.exit(1);
+            }
+            const targetDate = hasDateRange
+                ? options.today
+                    ? (0, dates_1.parseDateOption)()
+                    : (0, dates_1.parseDateOption)(options.date)
+                : undefined;
+            let hour = null;
+            if (options.hour) {
+                hour = (0, dates_1.parseHourOption)(options.hour);
+                if (!hour) {
+                    console.error('Error: hour format must be yyyy-mm-dd-hh');
+                    process.exit(1);
+                }
+            }
+            const alias = options.photos
+                ? 'photos'
+                : options.uploaded
+                    ? 'uploaded'
+                    : undefined;
+            const { images, empty } = await (0, memory_1.listCaptures)({
+                page,
+                limit,
+                maxPages,
+                useCache,
+                date: targetDate,
+                hour: hour || undefined,
+                alias,
+            });
+            if (empty === 'date' && targetDate) {
+                console.log(`No images found for ${targetDate.dateKey}.`);
+                return;
+            }
+            if (empty === 'hour') {
+                console.log(`No images found for ${options.hour} in cache.`);
+                return;
+            }
+            if (options.json) {
+                console.log(JSON.stringify(images, null, 2));
+                return;
+            }
+            // A search result carries less than a listing does, so the alias paths
+            // ask for their results to be cached as they are shown.
+            const imagesForDisplay = await (0, images_1.prepareImagesForDisplay)(images, {
+                cacheSearchResults: Boolean(alias),
+                enrichLocation: true,
+                useCache,
+            });
+            (0, images_1.printListImages)(imagesForDisplay);
+        }
+        catch (error) {
+            console.error('Error listing images:', error.message);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/locations.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerLocationsCommand = registerLocationsCommand;
+const credentials_1 = require("../credentials");
+const dates_1 = require("../dates");
+const options_1 = require("../options");
+const memory_1 = require("../services/memory");
+const analytics_1 = require("../services/analytics");
+function registerLocationsCommand(program) {
+    program
+        .command('locations')
+        .description('Rank metadata locations for a specific date')
+        .option('--date <yyyy|yyyy-mm|yyyy-mm-dd>', 'target date/range')
+        .option('--today', 'target today only (overrides default weekly range)')
+        .option('-l, --limit <number>', 'maximum ranking rows (max: 10)', '10')
+        .option('--max-pages <number>', 'max pages to scan before stopping', '10')
+        .option('-j, --json', 'output as JSON')
+        .option('--no-cache', 'force fetch from API')
+        .action(async (options) => {
+        await (0, credentials_1.ensureAccessToken)();
+        try {
+            const targetDate = (0, dates_1.resolveRankingRangeOption)(options);
+            const requestedLimit = (0, options_1.parsePositiveIntegerOption)(options.limit, '--limit');
+            const limit = Math.min(requestedLimit, 10);
+            const maxPages = (0, options_1.parsePositiveIntegerOption)(options.maxPages, '--max-pages');
+            const useCache = options.cache !== false;
+            let ranking = [];
+            let totalWithLocation = 0;
+            let totalImages = 0;
+            if (useCache) {
+                let cacheSummary = (0, analytics_1.buildLocationsRankingFromHourlyCache)(targetDate);
+                if (cacheSummary.totalImages === 0) {
+                    await (0, memory_1.warmDateCacheForLocations)(targetDate, maxPages, true);
+                    cacheSummary = (0, analytics_1.buildLocationsRankingFromHourlyCache)(targetDate);
+                }
+                ranking = cacheSummary.ranking;
+                totalWithLocation = cacheSummary.imageCountWithLocations;
+                totalImages = cacheSummary.totalImages;
+            }
+            else {
+                const imageIds = await (0, memory_1.warmDateCacheForLocations)(targetDate, maxPages, false);
+                ranking = (0, analytics_1.buildLocationsRankingFromCache)(imageIds);
+                totalWithLocation = ranking.reduce((sum, item) => sum + item.count, 0);
+                totalImages = imageIds.length;
+            }
+            const displayedRanking = ranking.slice(0, limit);
+            if (options.json) {
+                console.log(JSON.stringify({
+                    date: targetDate.dateKey,
+                    image_count: totalImages,
+                    location_image_count: totalWithLocation,
+                    total_locations: ranking.length,
+                    ranking: displayedRanking,
+                }, null, 2));
+                return;
+            }
+            if (ranking.length === 0) {
+                console.log(`No location metadata found for ${targetDate.dateKey}.`);
+                return;
+            }
+            console.log(`Locations on ${targetDate.dateKey}`);
+            displayedRanking.forEach((item, index) => {
+                console.log(`${index + 1}. ${item.location}: ${item.count}`);
+            });
+            console.log(`Total images with location metadata: ${totalWithLocation}`);
+        }
+        catch (error) {
+            console.error('Error ranking locations:', error.message);
+            process.exit(1);
+        }
+    });
+}