@yuiseki/gyazocli 0.1.1 → 0.2.0

package/dist/commands/search.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSearchCommand = registerSearchCommand;
+const api_1 = require("../api");
+const credentials_1 = require("../credentials");
+const format_1 = require("../format");
+const memory_1 = require("../services/memory");
+const images_1 = require("../services/images");
+function registerSearchCommand(program) {
+    program
+        .command('search [query]')
+        .description('Search images')
+        .option('-j, --json', 'output as JSON')
+        .option('--no-cache', 'force fetch from API')
+        .action(async (query, options) => {
+        await (0, credentials_1.ensureAccessToken)();
+        try {
+            if (!(0, format_1.normalizeText)(query)) {
+                console.error('Error: Query is required.');
+                console.error('Hint: Run `gyazo search -h` for usage.');
+                process.exit(1);
+            }
+            const images = await (0, api_1.searchImages)(query);
+            const useCache = options.cache !== false;
+            if (options.json) {
+                (0, memory_1.cacheSearchResultImages)(images);
+                console.log(JSON.stringify(images, null, 2));
+            }
+            else {
+                const imagesForDisplay = await (0, images_1.prepareImagesForDisplay)(images, {
+                    cacheSearchResults: true,
+                    enrichLocation: true,
+                    useCache,
+                });
+                (0, images_1.printListImages)(imagesForDisplay);
+            }
+        }
+        catch (error) {
+            console.error('Error searching images:', error.message);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/stats.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerStatsCommand = registerStatsCommand;
+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 registerStatsCommand(program) {
+    program
+        .command('stats')
+        .description('Show weekly stats summary in Markdown')
+        .option('--date <yyyy|yyyy-mm|yyyy-mm-dd>', 'window end date anchor (default: yesterday)')
+        .option('--days <number>', 'window length in days', '7')
+        .option('--top <number>', 'rows per section', '10')
+        .option('--max-pages <number>', 'max pages to fetch when warming cache', '10')
+        .option('--no-cache', 'force fetch from API')
+        .action(async (options) => {
+        await (0, credentials_1.ensureAccessToken)();
+        try {
+            const { range, days, startLabel, endLabel } = (0, dates_1.buildStatsDateRange)(options.date, options.days || '7');
+            const top = Math.min((0, options_1.parsePositiveIntegerOption)(options.top, '--top'), 20);
+            const maxPages = (0, options_1.parsePositiveIntegerOption)(options.maxPages, '--max-pages');
+            const useCache = options.cache !== false;
+            let uploadTime;
+            let apps = [];
+            let domains = [];
+            let tags = [];
+            let totalUploads = 0;
+            if (useCache) {
+                uploadTime = (0, analytics_1.buildUploadTimeSummaryFromHourlyCache)(range);
+                if (uploadTime.totalImages === 0) {
+                    await (0, memory_1.warmDateCacheForApps)(range, maxPages, true);
+                    uploadTime = (0, analytics_1.buildUploadTimeSummaryFromHourlyCache)(range);
+                }
+                let appsSummary = (0, analytics_1.buildAppsRankingFromHourlyCache)(range);
+                if (uploadTime.totalImages > 0 && appsSummary.totalImages === 0) {
+                    await (0, memory_1.warmDateCacheForApps)(range, maxPages, true);
+                    appsSummary = (0, analytics_1.buildAppsRankingFromHourlyCache)(range);
+                }
+                let domainsSummary = (0, analytics_1.buildDomainsRankingFromHourlyCache)(range);
+                if (uploadTime.totalImages > 0 && domainsSummary.totalImages === 0) {
+                    await (0, memory_1.warmDateCacheForDomains)(range, maxPages, true);
+                    domainsSummary = (0, analytics_1.buildDomainsRankingFromHourlyCache)(range);
+                }
+                let tagsSummary = (0, analytics_1.buildTagsRankingFromHourlyCache)(range);
+                if (uploadTime.totalImages > 0 && tagsSummary.totalImages === 0) {
+                    await (0, memory_1.warmDateCacheForTags)(range, maxPages, true);
+                    tagsSummary = (0, analytics_1.buildTagsRankingFromHourlyCache)(range);
+                }
+                apps = appsSummary.ranking;
+                domains = domainsSummary.ranking;
+                tags = tagsSummary.ranking;
+                totalUploads = uploadTime.totalImages;
+            }
+            else {
+                const imageIds = await (0, memory_1.warmDateCacheForTags)(range, maxPages, false);
+                uploadTime = (0, analytics_1.buildUploadTimeSummaryFromImageCache)(imageIds, range);
+                apps = (0, analytics_1.buildAppsRankingFromCache)(imageIds);
+                domains = (0, analytics_1.buildDomainsRankingFromCache)(imageIds);
+                tags = (0, analytics_1.buildTagsRankingFromCache)(imageIds).ranking;
+                totalUploads = uploadTime.totalImages;
+            }
+            console.log((0, analytics_1.renderStatsMarkdown)({
+                startLabel,
+                endLabel,
+                days,
+                totalUploads,
+                uploadTime,
+                apps,
+                domains,
+                tags,
+                top,
+            }));
+        }
+        catch (error) {
+            console.error('Error building stats:', error.message);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/summary.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSummaryCommand = registerSummaryCommand;
+const credentials_1 = require("../credentials");
+const dates_1 = require("../dates");
+const options_1 = require("../options");
+const analytics_1 = require("../services/analytics");
+function registerSummaryCommand(program) {
+    program
+        .command('summary')
+        .description('Show weekly summary with daily uploads and metadata rankings')
+        .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;
+            const dailySummaries = await (0, analytics_1.buildSummary)({ targetDate, maxPages, useCache });
+            if (options.json) {
+                console.log(JSON.stringify((0, analytics_1.toSummaryJson)(targetDate.dateKey, dailySummaries, limit), null, 2));
+                return;
+            }
+            console.log((0, analytics_1.renderSummaryText)({
+                dateKey: targetDate.dateKey,
+                dailySummaries,
+                limit,
+            }));
+        }
+        catch (error) {
+            console.error('Error building summary:', error.message);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/sync.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSyncCommand = registerSyncCommand;
+const api_1 = require("../api");
+const storage_1 = require("../storage");
+const credentials_1 = require("../credentials");
+const dates_1 = require("../dates");
+const options_1 = require("../options");
+function registerSyncCommand(program) {
+    program
+        .command('sync')
+        .description('Sync images from yesterday back to N days')
+        .option('--days <number>', 'number of days to sync (used when --date is omitted)')
+        .option('--date <yyyy|yyyy-mm|yyyy-mm-dd>', 'sync only this date/month/year range')
+        .option('--max-pages <number>', 'max pages to fetch', '10')
+        .action(async (options) => {
+        await (0, credentials_1.ensureAccessToken)();
+        if (options.date && options.days) {
+            console.error('Error: --date and --days cannot be used together.');
+            process.exit(1);
+        }
+        const maxPages = (0, options_1.parsePositiveIntegerOption)(options.maxPages, '--max-pages');
+        let startDate;
+        let endDate;
+        if (options.date) {
+            const parsed = (0, dates_1.parseDateOption)(options.date);
+            startDate = parsed.start;
+            endDate = parsed.end;
+        }
+        else {
+            const days = options.days ? (0, options_1.parsePositiveIntegerOption)(options.days, '--days') : 1;
+            const now = new Date();
+            endDate = new Date(now);
+            endDate.setDate(endDate.getDate() - 1);
+            endDate.setHours(23, 59, 59, 999);
+            startDate = new Date(now);
+            startDate.setDate(startDate.getDate() - days - 1);
+            startDate.setHours(0, 0, 0, 0);
+        }
+        console.log(`Syncing images between ${startDate.toISOString()} and ${endDate.toISOString()}...`);
+        const hourlyIndices = new Map();
+        for (let page = 1; page <= maxPages; page++) {
+            const images = await (0, api_1.listImages)(page, 100);
+            if (images.length === 0)
+                break;
+            let reachedLimit = false;
+            for (const img of images) {
+                const createdAt = new Date(img.created_at);
+                if (createdAt > endDate) {
+                    // Skip images newer than target range.
+                    continue;
+                }
+                if (createdAt < startDate) {
+                    reachedLimit = true;
+                    break;
+                }
+                // Add to hourly index
+                const y = createdAt.getFullYear().toString();
+                const m = (createdAt.getMonth() + 1).toString().padStart(2, '0');
+                const d = createdAt.getDate().toString().padStart(2, '0');
+                const h = createdAt.getHours().toString().padStart(2, '0');
+                const key = `${y}-${m}-${d}-${h}`;
+                if (!hourlyIndices.has(key))
+                    hourlyIndices.set(key, new Set());
+                hourlyIndices.get(key)?.add(img.image_id);
+                const cached = (0, storage_1.loadImageCache)(img.image_id);
+                if (cached && cached.ocr) {
+                    process.stdout.write(`s`);
+                    continue;
+                }
+                process.stdout.write(`.`);
+                try {
+                    const detail = await (0, api_1.getImageDetail)(img.image_id);
+                    (0, storage_1.saveImageCache)(img.image_id, detail);
+                    await new Promise(resolve => setTimeout(resolve, 200));
+                }
+                catch (e) {
+                    process.stdout.write(`x`);
+                }
+            }
+            console.log(`\nPage ${page} processed.`);
+            if (reachedLimit)
+                break;
+        }
+        // Save hourly indices
+        console.log(`Updating hourly indices...`);
+        for (const [key, ids] of hourlyIndices.entries()) {
+            const [y, m, d, h] = key.split('-');
+            const existing = (0, storage_1.loadHourlyCache)(y, m, d, h) || [];
+            const merged = Array.from(new Set([...existing, ...ids]));
+            (0, storage_1.saveHourlyCache)(y, m, d, h, merged);
+        }
+        console.log(`Sync complete.`);
+    });
+}

package/dist/commands/tags.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTagsCommand = registerTagsCommand;
+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 registerTagsCommand(program) {
+    program
+        .command('tags')
+        .description('Rank metadata tags 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 summary;
+            let totalImages = 0;
+            if (useCache) {
+                let cacheSummary = (0, analytics_1.buildTagsRankingFromHourlyCache)(targetDate);
+                if (cacheSummary.totalImages === 0) {
+                    await (0, memory_1.warmDateCacheForTags)(targetDate, maxPages, true);
+                    cacheSummary = (0, analytics_1.buildTagsRankingFromHourlyCache)(targetDate);
+                }
+                summary = cacheSummary;
+                totalImages = cacheSummary.totalImages;
+            }
+            else {
+                const imageIds = await (0, memory_1.warmDateCacheForTags)(targetDate, maxPages, false);
+                summary = (0, analytics_1.buildTagsRankingFromCache)(imageIds);
+                totalImages = imageIds.length;
+            }
+            const displayedRanking = summary.ranking.slice(0, limit);
+            if (options.json) {
+                console.log(JSON.stringify({
+                    date: targetDate.dateKey,
+                    image_count: totalImages,
+                    image_count_with_tags: summary.imageCountWithTags,
+                    total_tag_assignments: summary.totalTagAssignments,
+                    total_tags: summary.ranking.length,
+                    ranking: displayedRanking,
+                }, null, 2));
+                return;
+            }
+            if (summary.ranking.length === 0) {
+                console.log(`No tag metadata found for ${targetDate.dateKey}.`);
+                return;
+            }
+            console.log(`Tags on ${targetDate.dateKey}`);
+            displayedRanking.forEach((item, index) => {
+                console.log(`${index + 1}. #${item.tag}: ${item.count}`);
+            });
+            console.log(`Total images with tag metadata: ${summary.imageCountWithTags}`);
+        }
+        catch (error) {
+            console.error('Error ranking tags:', error.message);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/upload.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerUploadCommand = registerUploadCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const api_1 = require("../api");
+const credentials_1 = require("../credentials");
+const dates_1 = require("../dates");
+const images_1 = require("../services/images");
+function registerUploadCommand(program) {
+    program
+        .command('upload [path]')
+        .description('Upload an image file (or read image bytes from stdin)')
+        .option('-j, --json', 'output the upload response as JSON')
+        .option('--title <title>', 'image title')
+        .option('--app <app>', 'application name', 'gyazocli')
+        .option('--url <url>', 'source URL (sent as referer_url)')
+        .option('--timestamp <unix_timestamp>', 'created_at unix timestamp (current or past)')
+        .option('--desc <desc>', 'image description')
+        .action(async (inputPath, options) => {
+        await (0, credentials_1.ensureAccessToken)();
+        let imageData;
+        let filename = 'stdin-upload.bin';
+        if (inputPath && inputPath !== '-') {
+            const resolvedPath = path_1.default.resolve(inputPath);
+            if (!fs_1.default.existsSync(resolvedPath)) {
+                console.error(`Error: File not found: ${resolvedPath}`);
+                process.exit(1);
+            }
+            imageData = fs_1.default.readFileSync(resolvedPath);
+            filename = path_1.default.basename(resolvedPath);
+        }
+        else {
+            if (process.stdin.isTTY) {
+                console.error('Error: Provide an image path or pipe image data via stdin.');
+                console.error('Hint: Run `gyazo upload -h` for usage.');
+                process.exit(1);
+            }
+            imageData = await (0, images_1.readStdinBuffer)();
+            if (imageData.length === 0) {
+                console.error('Error: No image data received from stdin.');
+                process.exit(1);
+            }
+        }
+        const desc = (0, images_1.ensureUploadDescTag)(options.desc);
+        const timestamp = (0, dates_1.parseUploadTimestamp)(options.timestamp);
+        try {
+            const uploaded = await (0, api_1.uploadImage)({
+                imageData,
+                filename,
+                title: options.title,
+                app: options.app || 'gyazocli',
+                refererUrl: options.url,
+                desc,
+                timestamp,
+            });
+            if (options.json) {
+                console.log(JSON.stringify(uploaded, null, 2));
+            }
+            else {
+                console.log(uploaded.permalink_url);
+            }
+        }
+        catch (error) {
+            console.error('Error uploading image:', error.message);
+            process.exit(1);
+        }
+    });
+}

package/dist/dates.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * Dates, as this CLI means them: a day is a local day, because that is how the
+ * cache is laid out and how a person asking for "today" means it. Parses what
+ * --date and --days accept, builds the ranges the aggregations walk, and keys
+ * the hourly cache buckets.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DATE_OPTION_PROBLEMS = exports.WEEKDAY_LABELS = void 0;
+exports.isToday = isToday;
+exports.parseUploadTimestamp = parseUploadTimestamp;
+exports.tryParseDateOption = tryParseDateOption;
+exports.parseDateOption = parseDateOption;
+exports.formatDateYmd = formatDateYmd;
+exports.buildRecentWeekRangeUntilYesterday = buildRecentWeekRangeUntilYesterday;
+exports.resolveRankingRangeOption = resolveRankingRangeOption;
+exports.buildStatsDateRange = buildStatsDateRange;
+exports.getDateHourStrings = getDateHourStrings;
+exports.buildHourlyBucketKey = buildHourlyBucketKey;
+exports.splitHourlyBucketKey = splitHourlyBucketKey;
+exports.toDateParts = toDateParts;
+exports.getDatePartsInRange = getDatePartsInRange;
+exports.parseHourOption = parseHourOption;
+const options_1 = require("./options");
+exports.WEEKDAY_LABELS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+function isToday(date) {
+    const today = new Date();
+    return date.getDate() === today.getDate() &&
+        date.getMonth() === today.getMonth() &&
+        date.getFullYear() === today.getFullYear();
+}
+function parseUploadTimestamp(value) {
+    if (!value)
+        return undefined;
+    if (!/^\d+$/.test(value)) {
+        console.error('Error: --timestamp must be a unix timestamp in seconds.');
+        process.exit(1);
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        console.error('Error: --timestamp is out of range.');
+        process.exit(1);
+    }
+    const now = Math.floor(Date.now() / 1000);
+    if (parsed > now) {
+        console.error('Error: --timestamp must be current time or in the past.');
+        process.exit(1);
+    }
+    return parsed;
+}
+/**
+ * Reads a date the way --date accepts it, without deciding what to do when it
+ * cannot: the CLI reports and exits, the MCP server throws.
+ */
+function tryParseDateOption(value) {
+    if (!value) {
+        const today = new Date();
+        const year = String(today.getFullYear());
+        const month = String(today.getMonth() + 1).padStart(2, '0');
+        const day = String(today.getDate()).padStart(2, '0');
+        return {
+            ok: true,
+            value: {
+                granularity: 'day',
+                dateKey: `${year}-${month}-${day}`,
+                start: new Date(today.getFullYear(), today.getMonth(), today.getDate(), 0, 0, 0, 0),
+                end: new Date(today.getFullYear(), today.getMonth(), today.getDate(), 23, 59, 59, 999),
+            },
+        };
+    }
+    if (/^\d{4}$/.test(value)) {
+        const year = Number(value);
+        return {
+            ok: true,
+            value: {
+                granularity: 'year',
+                dateKey: value,
+                start: new Date(year, 0, 1, 0, 0, 0, 0),
+                end: new Date(year, 11, 31, 23, 59, 59, 999),
+            },
+        };
+    }
+    if (/^\d{4}-\d{2}$/.test(value)) {
+        const [yearText, monthText] = value.split('-');
+        const year = Number(yearText);
+        const month = Number(monthText);
+        const probe = new Date(year, month - 1, 1);
+        if (probe.getFullYear() !== year || probe.getMonth() !== month - 1) {
+            return { ok: false, problem: 'month' };
+        }
+        return {
+            ok: true,
+            value: {
+                granularity: 'month',
+                dateKey: value,
+                start: new Date(year, month - 1, 1, 0, 0, 0, 0),
+                end: new Date(year, month, 0, 23, 59, 59, 999),
+            },
+        };
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        const [yearText, monthText, dayText] = value.split('-');
+        const year = Number(yearText);
+        const month = Number(monthText);
+        const day = Number(dayText);
+        const probe = new Date(year, month - 1, day);
+        if (probe.getFullYear() !== year ||
+            probe.getMonth() !== month - 1 ||
+            probe.getDate() !== day) {
+            return { ok: false, problem: 'day' };
+        }
+        return {
+            ok: true,
+            value: {
+                granularity: 'day',
+                dateKey: value,
+                start: new Date(year, month - 1, day, 0, 0, 0, 0),
+                end: new Date(year, month - 1, day, 23, 59, 59, 999),
+            },
+        };
+    }
+    return { ok: false, problem: 'format' };
+}
+exports.DATE_OPTION_PROBLEMS = {
+    month: '--date month is invalid.',
+    day: '--date day is invalid.',
+    format: '--date format must be yyyy or yyyy-mm or yyyy-mm-dd.',
+};
+function parseDateOption(value) {
+    const parsed = tryParseDateOption(value);
+    if (!parsed.ok) {
+        console.error(`Error: ${exports.DATE_OPTION_PROBLEMS[parsed.problem]}`);
+        process.exit(1);
+    }
+    return parsed.value;
+}
+function formatDateYmd(date) {
+    const year = String(date.getFullYear());
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+function buildRecentWeekRangeUntilYesterday() {
+    const today = new Date();
+    const end = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 1, 23, 59, 59, 999);
+    const start = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 8, 0, 0, 0, 0);
+    return {
+        granularity: 'day',
+        dateKey: `${formatDateYmd(start)}..${formatDateYmd(end)}`,
+        start,
+        end,
+    };
+}
+function resolveRankingRangeOption(options) {
+    if (options.today && options.date) {
+        console.error('Error: --today and --date cannot be used together.');
+        process.exit(1);
+    }
+    if (options.today) {
+        return parseDateOption();
+    }
+    if (options.date) {
+        return parseDateOption(options.date);
+    }
+    return buildRecentWeekRangeUntilYesterday();
+}
+function buildStatsDateRange(dateOption, daysOption) {
+    if (!dateOption && daysOption === '7') {
+        const weekly = buildRecentWeekRangeUntilYesterday();
+        return {
+            range: weekly,
+            days: 7,
+            startLabel: formatDateYmd(weekly.start),
+            endLabel: formatDateYmd(weekly.end),
+        };
+    }
+    const days = (0, options_1.parsePositiveIntegerOption)(daysOption, '--days');
+    let endDate;
+    if (dateOption) {
+        const parsed = parseDateOption(dateOption);
+        endDate = new Date(parsed.end);
+    }
+    else {
+        const now = new Date();
+        endDate = new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1, 23, 59, 59, 999);
+    }
+    const startDate = new Date(endDate.getFullYear(), endDate.getMonth(), endDate.getDate(), 0, 0, 0, 0);
+    startDate.setDate(startDate.getDate() - (days - 1));
+    const startLabel = formatDateYmd(startDate);
+    const endLabel = formatDateYmd(endDate);
+    return {
+        range: {
+            granularity: 'day',
+            dateKey: `${startLabel}..${endLabel}`,
+            start: startDate,
+            end: endDate,
+        },
+        days,
+        startLabel,
+        endLabel,
+    };
+}
+function getDateHourStrings() {
+    const hours = [];
+    for (let hour = 0; hour < 24; hour++) {
+        hours.push(String(hour).padStart(2, '0'));
+    }
+    return hours;
+}
+function buildHourlyBucketKey(year, month, day, hour) {
+    return `${year}-${month}-${day}-${hour}`;
+}
+function splitHourlyBucketKey(key) {
+    const [year, month, day, hour] = key.split('-');
+    return { year, month, day, hour };
+}
+function toDateParts(date) {
+    return {
+        year: String(date.getFullYear()),
+        month: String(date.getMonth() + 1).padStart(2, '0'),
+        day: String(date.getDate()).padStart(2, '0'),
+        hour: String(date.getHours()).padStart(2, '0'),
+    };
+}
+function getDatePartsInRange(start, end) {
+    const dates = [];
+    const cursor = new Date(start.getFullYear(), start.getMonth(), start.getDate(), 0, 0, 0, 0);
+    const last = new Date(end.getFullYear(), end.getMonth(), end.getDate(), 0, 0, 0, 0);
+    while (cursor.getTime() <= last.getTime()) {
+        dates.push({
+            year: String(cursor.getFullYear()),
+            month: String(cursor.getMonth() + 1).padStart(2, '0'),
+            day: String(cursor.getDate()).padStart(2, '0'),
+        });
+        cursor.setDate(cursor.getDate() + 1);
+    }
+    return dates;
+}
+/**
+ * `yyyy-mm-dd-hh`, the shape the hourly cache is keyed by. Returns null rather
+ * than reporting, because how to report differs between the CLI and the MCP
+ * server.
+ */
+function parseHourOption(value) {
+    const parts = (value || '').split('-');
+    if (parts.length !== 4)
+        return null;
+    const [year, month, day, hour] = parts;
+    return { year, month, day, hour };
+}