@yuiseki/gyazocli 0.0.1 → 0.1.1

package/README.md

@@ -16,6 +16,76 @@ gyazo sync --days 10
 gyazo --help
 ```
 
+### Shorthands
+
+The first argument may stand on its own when it is unambiguous. A Gyazo
+image ID is 32 hex characters, so it can never be mistaken for a path.
+
+```bash
+gyazo path/to/image.png                              # same as: gyazo upload path/to/image.png
+gyazo 49a008e2f254f513063b6ec4d3082940               # same as: gyazo get 49a008e2f254f513063b6ec4d3082940
+gyazo https://gyazo.com/49a008e2f254f513063b6ec4d3082940   # same as above
+gyazo https://gyazo.com/collections/21ca16a1023c667a7a437be561a65018  # same as: gyazo collection <id>
+```
+
+A collection ID is 32 hex characters just like an image ID, so a bare ID is read
+as an image. Only the `/collections/<id>` URL form is unambiguous. When a command
+is given the wrong kind of ID it points at the other one.
+
+Subcommand names always win, so `gyazo search` stays `gyazo search` even
+if a file of that name exists in the working directory.
+
+### Detail
+
+- `gyazo config set token <token>`: Save your access token
+- `gyazo config get token|me`: Show saved token (masked) or `me` profile info
+- `gyazo ls` (`gyazo list`): List images (`--date`/`--today`, `--photos`, `--uploaded`, `-H` available; `--photos/--uploaded` can be combined with `--date`/`--today`)
+- `gyazo search <query>`: Search images
+- `gyazo collection <collection_id|url>` (`col`, `cols`, `collections`): Show a collection and the images in it (`--sort added|created|captured`, `-A`, `-j` available)
+- `gyazo get <image_id|url>`: Show image details (`--ocr`, `--objects`, `-j` available). Accepts a bare image ID, a `https://gyazo.com/<id>` permalink, or a `https://i.gyazo.com/<id>.png` URL
+- `gyazo apps|domains|tags|locations`: Show rankings
+- `gyazo summary`: Show day-by-day weekly summary in Markdown (`##`/`###` headings, image count, apps, domains, tags, locations per day)
+- `gyazo stats`: Show weekly summary
+- `gyazo upload [path]`: Upload an image (uses stdin when path is omitted). Prints the permalink URL alone; use `-j` for the full response
+- `gyazo sync`: Sync cache
+
+Date range notes:
+- Default range for `apps|domains|tags|locations|stats` is from 8 days ago to yesterday
+- Use `--today` for today only, or `--date <yyyy|yyyy-mm|yyyy-mm-dd>` for a custom range
+
+JSON output:
+- `-j, --json` is available for `config get`, `ls`, `get`, `search`, `apps`, `domains`, `tags`, `locations`, `summary`, and `upload`
+
+### Anonymous access
+
+A Gyazo ID is long enough to act as the key to the image, so public images and
+collections read fine with no token. An access token, on the other hand, allows
+things this CLI does not expose (deleting, for one), so the way to give an agent
+read-only access is to give it no token at all.
+
+```bash
+gyazo collection <id>               # uses the token if there is one, otherwise reads anonymously
+gyazo collection <id> --anonymous   # ignores the token even when one is configured
+```
+
+Anonymous reads have limits worth knowing:
+
+- A collection or image set to `only_me` returns 404, indistinguishable from one
+  that does not exist. That is deliberate: it keeps the ID from confirming what
+  exists.
+- An image with `metadata_is_public: false` still returns 200, but `metadata` and
+  `created_at` come back `null`, so OCR, EXIF and location are gone. The web
+  endpoint withholds these even from the owner's token; `gyazo get` uses
+  `api.gyazo.com` for that reason.
+
+Exit codes:
+- `0` on success, `1` on a usage error or a failed API call
+
+Environment variables:
+- `GYAZO_ACCESS_TOKEN`: access token (takes precedence over the saved config)
+- `GYAZO_CACHE_DIR`: cache location
+- `GYAZO_API_ORIGIN` / `GYAZO_UPLOAD_ORIGIN` / `GYAZO_WEB_ORIGIN`: override the endpoints (used by the test suite)
+
 ## Development
 
 ### Build
@@ -25,6 +95,12 @@ npm install
 npm run build
 ```
 
+### Test
+
+```bash
+npm test
+```
+
 ### Link local CLI with npm link
 
 ```bash

package/dist/api.js

@@ -7,18 +7,35 @@ exports.listImages = listImages;
 exports.getImageDetail = getImageDetail;
 exports.searchImages = searchImages;
 exports.getCurrentUser = getCurrentUser;
+exports.getCollection = getCollection;
 exports.uploadImage = uploadImage;
 const axios_1 = __importDefault(require("axios"));
 const form_data_1 = __importDefault(require("form-data"));
 const config_1 = require("./config");
-const API_BASE_URL = 'https://api.gyazo.com/api/images';
-const API_SEARCH_URL = 'https://api.gyazo.com/api/search';
-const API_USERS_ME_URL = 'https://api.gyazo.com/api/users/me';
-const API_UPLOAD_URL = 'https://upload.gyazo.com/api/upload';
-async function requestWithRetry(url, params = {}) {
-    const headers = { Authorization: `Bearer ${config_1.config.GYAZO_ACCESS_TOKEN}` };
+const DEFAULT_API_ORIGIN = 'https://api.gyazo.com';
+const DEFAULT_UPLOAD_ORIGIN = 'https://upload.gyazo.com';
+const DEFAULT_WEB_ORIGIN = 'https://gyazo.com';
+function stripTrailingSlash(origin) {
+    return origin.replace(/\/+$/, '');
+}
+function apiOrigin() {
+    return stripTrailingSlash(config_1.config.GYAZO_API_ORIGIN || DEFAULT_API_ORIGIN);
+}
+function uploadOrigin() {
+    return stripTrailingSlash(config_1.config.GYAZO_UPLOAD_ORIGIN || DEFAULT_UPLOAD_ORIGIN);
+}
+function webOrigin() {
+    return stripTrailingSlash(config_1.config.GYAZO_WEB_ORIGIN || DEFAULT_WEB_ORIGIN);
+}
+const apiBaseUrl = () => `${apiOrigin()}/api/images`;
+const apiSearchUrl = () => `${apiOrigin()}/api/search`;
+const apiUsersMeUrl = () => `${apiOrigin()}/api/users/me`;
+const apiUploadUrl = () => `${uploadOrigin()}/api/upload`;
+const webCollectionUrl = (id) => `${webOrigin()}/collections/${id}.json`;
+async function requestWithRetry(url, params = {}, headers) {
+    const requestHeaders = headers ?? { Authorization: `Bearer ${config_1.config.GYAZO_ACCESS_TOKEN}` };
     try {
-        const response = await axios_1.default.get(url, { headers, params });
+        const response = await axios_1.default.get(url, { headers: requestHeaders, params });
         return response.data;
     }
     catch (error) {
@@ -26,22 +43,35 @@ async function requestWithRetry(url, params = {}) {
             const retryAfter = parseInt(error.response.headers['retry-after'] || '5', 10);
             console.warn(`Rate limited. Retrying after ${retryAfter} seconds...`);
             await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
-            return requestWithRetry(url, params);
+            return requestWithRetry(url, params, headers);
         }
         throw error;
     }
 }
 async function listImages(page = 1, perPage = 20) {
-    return requestWithRetry(API_BASE_URL, { page, per_page: perPage });
+    return requestWithRetry(apiBaseUrl(), { page, per_page: perPage });
 }
 async function getImageDetail(imageId) {
-    return requestWithRetry(`${API_BASE_URL}/${imageId}`);
+    return requestWithRetry(`${apiBaseUrl()}/${imageId}`);
 }
 async function searchImages(query, page = 1, perPage = 20) {
-    return requestWithRetry(API_SEARCH_URL, { query, page, per: perPage });
+    return requestWithRetry(apiSearchUrl(), { query, page, per: perPage });
 }
 async function getCurrentUser() {
-    return requestWithRetry(API_USERS_ME_URL);
+    return requestWithRetry(apiUsersMeUrl());
+}
+/**
+ * Collections are read through the public web endpoint. It returns the
+ * collection metadata plus the first 100 images with their full detail in a
+ * single request, and it works without a token for public collections, which
+ * is what lets an agent run read-only with no credentials at all.
+ */
+async function getCollection(collectionId, options = {}) {
+    const headers = {};
+    if (!options.anonymous && config_1.config.GYAZO_ACCESS_TOKEN) {
+        headers.Authorization = `Bearer ${config_1.config.GYAZO_ACCESS_TOKEN}`;
+    }
+    return requestWithRetry(webCollectionUrl(collectionId), {}, headers);
 }
 async function uploadImage(options) {
     const form = new form_data_1.default();
@@ -60,7 +90,7 @@ async function uploadImage(options) {
     if (typeof options.timestamp === 'number') {
         form.append('created_at', String(options.timestamp));
     }
-    const response = await axios_1.default.post(API_UPLOAD_URL, form, {
+    const response = await axios_1.default.post(apiUploadUrl(), form, {
         headers: form.getHeaders(),
     });
     return response.data;

package/dist/config.js

@@ -13,12 +13,18 @@ const configSchema = zod_1.z.object({
     GYAZO_CLIENT_ID: zod_1.z.string().optional(),
     GYAZO_CLIENT_SECRET: zod_1.z.string().optional(),
     GYAZO_CACHE_DIR: zod_1.z.string().optional(),
+    GYAZO_API_ORIGIN: zod_1.z.string().optional(),
+    GYAZO_UPLOAD_ORIGIN: zod_1.z.string().optional(),
+    GYAZO_WEB_ORIGIN: zod_1.z.string().optional(),
 });
 exports.config = configSchema.parse({
     GYAZO_ACCESS_TOKEN: process.env.GYAZO_ACCESS_TOKEN,
     GYAZO_CLIENT_ID: process.env.GYAZO_CLIENT_ID,
     GYAZO_CLIENT_SECRET: process.env.GYAZO_CLIENT_SECRET,
     GYAZO_CACHE_DIR: process.env.GYAZO_CACHE_DIR,
+    GYAZO_API_ORIGIN: process.env.GYAZO_API_ORIGIN,
+    GYAZO_UPLOAD_ORIGIN: process.env.GYAZO_UPLOAD_ORIGIN,
+    GYAZO_WEB_ORIGIN: process.env.GYAZO_WEB_ORIGIN,
 });
 function setAccessToken(token) {
     exports.config.GYAZO_ACCESS_TOKEN = token;

package/dist/credentials.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getStoredConfig = getStoredConfig;
 exports.setStoredConfig = setStoredConfig;
+exports.resolveAccessToken = resolveAccessToken;
 exports.ensureAccessToken = ensureAccessToken;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -44,7 +45,11 @@ function setStoredConfig(key, value) {
     fs_1.default.writeFileSync(CREDENTIALS_FILE, JSON.stringify(stored, null, 2));
     console.error(`Config set: ${key}=${value}`);
 }
-async function ensureAccessToken() {
+/**
+ * Load the access token if there is one, without failing when there is not.
+ * Read-only commands fall back to anonymous access instead of exiting.
+ */
+function resolveAccessToken() {
     if (config_1.config.GYAZO_ACCESS_TOKEN) {
         return config_1.config.GYAZO_ACCESS_TOKEN;
     }
@@ -53,6 +58,13 @@ async function ensureAccessToken() {
         (0, config_1.setAccessToken)(storedToken);
         return storedToken;
     }
+    return undefined;
+}
+async function ensureAccessToken() {
+    const token = resolveAccessToken();
+    if (token) {
+        return token;
+    }
     console.error('Error: Gyazo Access Token is not set.');
     console.error('Please run the following command to set your access token:');
     console.error('  gyazo config set token <your_access_token>');

package/dist/index.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeImageId = normalizeImageId;
+exports.normalizeCollectionId = normalizeCollectionId;
 const commander_1 = require("commander");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -13,10 +15,123 @@ const credentials_1 = require("./credentials");
 const program = new commander_1.Command();
 const UPLOAD_DESC_TAG = '#gyazocli_uploads';
 const WEEKDAY_LABELS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const IMAGE_ID_PATTERN = /^[0-9a-f]{32}$/i;
+const GYAZO_HOST_PATTERN = /(^|\.)gyazo\.com$/i;
+/**
+ * Accept either a bare Gyazo image id (32 hex characters) or any Gyazo URL that
+ * carries one, and return the canonical lowercase id. Returns null otherwise.
+ */
+function normalizeImageId(input) {
+    const trimmed = (input || '').trim();
+    if (!trimmed)
+        return null;
+    if (IMAGE_ID_PATTERN.test(trimmed)) {
+        return trimmed.toLowerCase();
+    }
+    if (!/^https?:\/\//i.test(trimmed)) {
+        return null;
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (!GYAZO_HOST_PATTERN.test(url.hostname)) {
+        return null;
+    }
+    const segments = url.pathname.split('/').filter(Boolean);
+    const lastSegment = segments[segments.length - 1];
+    if (!lastSegment)
+        return null;
+    // /collections/<id> is a collection, not an image.
+    if (segments[segments.length - 2] === 'collections')
+        return null;
+    const withoutExtension = lastSegment.replace(/\.[a-z0-9]+$/i, '');
+    return IMAGE_ID_PATTERN.test(withoutExtension) ? withoutExtension.toLowerCase() : null;
+}
+const COLLECTION_SORTS = ['added', 'created', 'captured'];
+/**
+ * A collection ID looks exactly like an image ID (32 hex characters), so only
+ * the URL form tells the two apart. `/collections/<id>` is a collection;
+ * `/<id>` is an image.
+ */
+function normalizeCollectionId(input) {
+    const trimmed = (input || '').trim();
+    if (!trimmed)
+        return null;
+    if (IMAGE_ID_PATTERN.test(trimmed)) {
+        return trimmed.toLowerCase();
+    }
+    if (!/^https?:\/\//i.test(trimmed)) {
+        return null;
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (!GYAZO_HOST_PATTERN.test(url.hostname)) {
+        return null;
+    }
+    const segments = url.pathname.split('/').filter(Boolean);
+    if (segments.length < 2 || segments[segments.length - 2] !== 'collections') {
+        return null;
+    }
+    const withoutExtension = segments[segments.length - 1].replace(/\.[a-z0-9]+$/i, '');
+    return IMAGE_ID_PATTERN.test(withoutExtension) ? withoutExtension.toLowerCase() : null;
+}
+function requireCollectionId(input) {
+    const collectionId = normalizeCollectionId(input);
+    if (!collectionId) {
+        console.error(`Error: '${input}' is not a Gyazo collection ID or URL.`);
+        console.error('Hint: pass a 32-character collection ID or a https://gyazo.com/collections/<id> URL.');
+        process.exit(1);
+    }
+    return collectionId;
+}
+function parseCollectionSort(value) {
+    if (value === undefined || value === null)
+        return 'added';
+    if (COLLECTION_SORTS.includes(String(value))) {
+        return String(value);
+    }
+    console.error(`Error: --sort must be one of ${COLLECTION_SORTS.join(', ')}.`);
+    process.exit(1);
+}
+function collectionSortKey(image, sort) {
+    if (sort === 'captured') {
+        return image?.exif_captured_at || image?.metadata?.exif_normalized?.time || image?.created_at || '';
+    }
+    return image?.created_at || '';
+}
+function sortCollectionImages(images, sort) {
+    if (sort === 'added')
+        return images;
+    // Newest first, matching how `list` presents images.
+    return [...images].sort((a, b) => collectionSortKey(b, sort).localeCompare(collectionSortKey(a, sort)));
+}
+function requireImageId(input) {
+    const imageId = normalizeImageId(input);
+    if (!imageId) {
+        console.error(`Error: '${input}' is not a Gyazo image ID or URL.`);
+        if (normalizeCollectionId(input)) {
+            console.error(`Hint: that looks like a collection. Try \`gyazo collection ${input}\`.`);
+        }
+        else {
+            console.error('Hint: pass a 32-character image ID or a https://gyazo.com/<id> URL.');
+        }
+        process.exit(1);
+    }
+    return imageId;
+}
 program
     .name('gyazo')
     .description('Gyazo Memory CLI for AI Secretary')
-    .version('0.0.1');
+    .version('0.1.1');
 // Config Command
 const configCmd = program.command('config').description('Manage configuration');
 configCmd
@@ -540,6 +655,19 @@ function getDatePartsInRange(start, end) {
     }
     return dates;
 }
+function loadImageIdsFromDateRangeCache(targetDate) {
+    const imageIds = new Set();
+    const dates = getDatePartsInRange(targetDate.start, targetDate.end);
+    const hours = getDateHourStrings();
+    for (const date of dates) {
+        for (const hour of hours) {
+            const ids = (0, storage_1.loadHourlyCache)(date.year, date.month, date.day, hour) || [];
+            for (const id of ids)
+                imageIds.add(id);
+        }
+    }
+    return Array.from(imageIds);
+}
 function normalizeRankingValues(values) {
     const uniqueByLower = new Map();
     for (const raw of values) {
@@ -630,6 +758,59 @@ async function warmDateCacheForTags(targetDate, maxPages, useCache) {
 async function warmDateCacheForLocations(targetDate, maxPages, useCache) {
     return warmDateCacheForRanking(targetDate, maxPages, useCache, 'locations', extractImageLocations);
 }
+async function warmDateCacheForList(targetDate, maxPages, useCache) {
+    const hourlyIndices = new Map();
+    const imageIds = new Set();
+    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 (Number.isNaN(createdAt.getTime()))
+                continue;
+            if (createdAt > targetDate.end)
+                continue;
+            if (createdAt < targetDate.start) {
+                reachedLimit = true;
+                break;
+            }
+            const dateParts = toDateParts(createdAt);
+            const bucketKey = buildHourlyBucketKey(dateParts.year, dateParts.month, dateParts.day, dateParts.hour);
+            if (!hourlyIndices.has(bucketKey)) {
+                hourlyIndices.set(bucketKey, new Set());
+            }
+            hourlyIndices.get(bucketKey)?.add(img.image_id);
+            imageIds.add(img.image_id);
+            let merged = img;
+            const cached = useCache ? (0, storage_1.loadImageCache)(img.image_id) : null;
+            if (cached) {
+                merged = mergeImageForDisplay(img, cached);
+            }
+            (0, storage_1.saveImageCache)(img.image_id, merged);
+        }
+        if (reachedLimit)
+            break;
+    }
+    for (const [bucketKey, current] of hourlyIndices.entries()) {
+        const { year, month, day, hour } = splitHourlyBucketKey(bucketKey);
+        if (useCache) {
+            const existing = (0, storage_1.loadHourlyCache)(year, month, day, hour) || [];
+            for (const id of existing)
+                current.add(id);
+        }
+        (0, storage_1.saveHourlyCache)(year, month, day, hour, Array.from(current));
+        for (const id of current)
+            imageIds.add(id);
+    }
+    if (useCache) {
+        for (const id of loadImageIdsFromDateRangeCache(targetDate)) {
+            imageIds.add(id);
+        }
+    }
+    return Array.from(imageIds);
+}
 async function warmDateCacheForRanking(targetDate, maxPages, useCache, metadataKind, extractValues) {
     const hourlyIndices = new Map();
     const hourlyMetadataEntries = new Map();
@@ -975,6 +1156,122 @@ function buildUploadTimeSummaryFromImageCache(imageIds, targetDate) {
         }),
     };
 }
+function buildDailyUploadCountsFromHourlyCache(targetDate) {
+    const dates = getDatePartsInRange(targetDate.start, targetDate.end);
+    const hours = getDateHourStrings();
+    const byDate = new Map();
+    for (const date of dates) {
+        const dateLabel = `${date.year}-${date.month}-${date.day}`;
+        if (!byDate.has(dateLabel)) {
+            byDate.set(dateLabel, new Set());
+        }
+        const ids = byDate.get(dateLabel);
+        for (const hour of hours) {
+            const imageIds = (0, storage_1.loadHourlyCache)(date.year, date.month, date.day, hour) || [];
+            for (const imageId of imageIds)
+                ids.add(imageId);
+        }
+    }
+    return dates.map(date => {
+        const dateLabel = `${date.year}-${date.month}-${date.day}`;
+        return {
+            date: dateLabel,
+            count: byDate.get(dateLabel)?.size || 0,
+        };
+    });
+}
+function buildDailyUploadCountsFromImageCache(imageIds, targetDate) {
+    const dates = getDatePartsInRange(targetDate.start, targetDate.end);
+    const byDate = new Map();
+    for (const date of dates) {
+        const dateLabel = `${date.year}-${date.month}-${date.day}`;
+        byDate.set(dateLabel, new Set());
+    }
+    for (const imageId of imageIds) {
+        const image = (0, storage_1.loadImageCache)(imageId);
+        const createdAtText = normalizeText(image?.created_at);
+        if (!createdAtText)
+            continue;
+        const createdAt = new Date(createdAtText);
+        if (Number.isNaN(createdAt.getTime()))
+            continue;
+        if (createdAt < targetDate.start || createdAt > targetDate.end)
+            continue;
+        const dateLabel = formatDateYmd(createdAt);
+        const ids = byDate.get(dateLabel);
+        if (!ids)
+            continue;
+        ids.add(imageId);
+    }
+    return dates.map(date => {
+        const dateLabel = `${date.year}-${date.month}-${date.day}`;
+        return {
+            date: dateLabel,
+            count: byDate.get(dateLabel)?.size || 0,
+        };
+    });
+}
+function buildDailySummariesFromImageCache(targetDate) {
+    const dates = getDatePartsInRange(targetDate.start, targetDate.end);
+    const hours = getDateHourStrings();
+    const summaries = [];
+    for (const date of dates) {
+        const dateLabel = `${date.year}-${date.month}-${date.day}`;
+        const imageIds = new Set();
+        for (const hour of hours) {
+            const ids = (0, storage_1.loadHourlyCache)(date.year, date.month, date.day, hour) || [];
+            for (const id of ids)
+                imageIds.add(id);
+        }
+        const appCounts = new Map();
+        const domainCounts = new Map();
+        const tagCounts = new Map();
+        const locationCounts = new Map();
+        for (const imageId of imageIds) {
+            const image = (0, storage_1.loadImageCache)(imageId);
+            if (!image)
+                continue;
+            for (const app of extractImageApps(image)) {
+                appCounts.set(app, (appCounts.get(app) || 0) + 1);
+            }
+            for (const domain of extractImageDomains(image)) {
+                domainCounts.set(domain, (domainCounts.get(domain) || 0) + 1);
+            }
+            for (const tag of extractImageTags(image)) {
+                tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
+            }
+            for (const location of extractImageLocations(image)) {
+                locationCounts.set(location, (locationCounts.get(location) || 0) + 1);
+            }
+        }
+        const sortEntries = (a, b) => {
+            if (b[1] !== a[1])
+                return b[1] - a[1];
+            return a[0].localeCompare(b[0]);
+        };
+        const apps = Array.from(appCounts.entries())
+            .sort(sortEntries)
+            .map(([app, count]) => ({ app, count }));
+        const domains = Array.from(domainCounts.entries())
+            .sort(sortEntries)
+            .map(([domain, count]) => ({ domain, count }));
+        const tags = Array.from(tagCounts.entries())
+            .sort(sortEntries)
+            .map(([tag, count]) => ({ tag, count }));
+        const locations = Array.from(locationCounts.entries())
+            .sort(sortEntries)
+            .map(([location, count]) => ({ location, count }));
+        summaries.push({
+            date: dateLabel,
+            imageCount: imageIds.size,
+            apps,
+            domains,
+            tags,
+            locations,
+        });
+    }
+    return summaries;
+}
 function appendStatsRankSection(lines, title, rows, top) {
     lines.push(`### ${title}`);
     const filtered = rows.filter(row => row.count > 0).slice(0, top);
@@ -1008,6 +1305,34 @@ function renderStatsMarkdown(params) {
     appendStatsRankSection(lines, 'Tags', params.tags.map(item => ({ label: `#${item.tag}`, count: item.count })), params.top);
     return lines.join('\n').trimEnd();
 }
+function renderSummaryText(params) {
+    const appendRankSection = (lines, title, rows, limit) => {
+        lines.push(`- ${title}:`);
+        const items = rows.filter(row => row.count > 0).slice(0, limit);
+        if (items.length === 0) {
+            lines.push('  - (none)');
+            return;
+        }
+        for (const row of items) {
+            lines.push(`  - ${row.label}${row.count > 1 ? ` (${row.count})` : ''}`);
+        }
+    };
+    const lines = [];
+    lines.push('## Gyazo Summary');
+    lines.push('');
+    lines.push(`- Window: ${params.dateKey}`);
+    lines.push('');
+    for (const day of params.dailySummaries) {
+        lines.push(`### ${day.date}`);
+        lines.push(`- Image count: ${day.imageCount}`);
+        appendRankSection(lines, 'Apps', day.apps.map(item => ({ label: item.app, count: item.count })), params.limit);
+        appendRankSection(lines, 'Domains', day.domains.map(item => ({ label: item.domain, count: item.count })), params.limit);
+        appendRankSection(lines, 'Tags', day.tags.map(item => ({ label: `#${item.tag}`, count: item.count })), params.limit);
+        appendRankSection(lines, 'Locations', day.locations.map(item => ({ label: item.location, count: item.count })), params.limit);
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
 async function readStdinBuffer() {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -1018,6 +1343,42 @@ async function readStdinBuffer() {
         process.stdin.on('error', reject);
     });
 }
+function printCollectionMarkdown(collection, images) {
+    const lines = [];
+    lines.push('## Gyazo Collection');
+    lines.push('');
+    const name = normalizeText(collection?.name);
+    if (name)
+        lines.push(`- Name: ${name}`);
+    const collectionId = collection?.id;
+    const url = collection?.url || (collectionId ? `https://gyazo.com/collections/${collectionId}` : undefined);
+    if (url)
+        lines.push(`- URL: <${url}>`);
+    const description = normalizeText(collection?.description);
+    if (description)
+        lines.push(`- Description: ${description}`);
+    const owner = normalizeText(collection?.user?.name);
+    if (owner)
+        lines.push(`- Owner: ${owner}`);
+    const total = collection?.total_image_count;
+    const shown = images.length;
+    const truncated = typeof total === 'number' && total > shown;
+    lines.push(`- Images: ${truncated ? `${shown} of ${total}` : shown}`);
+    const updatedAt = normalizeText(collection?.list_updated_at);
+    if (updatedAt)
+        lines.push(`- Updated at: ${formatCreatedAt(updatedAt)}`);
+    console.log(lines.join('\n'));
+    if (truncated) {
+        console.log('');
+        console.log('Note: this endpoint returns only the first 100 images of a collection.');
+    }
+    if (shown > 0) {
+        console.log('');
+        console.log('### Images');
+        console.log('');
+        printListImages(images);
+    }
+}
 function printGetMarkdown(image, ocrDescription, objects = []) {
     const lines = [];
     lines.push('## Gyazo Image');
@@ -1057,7 +1418,7 @@ function printGetMarkdown(image, ocrDescription, objects = []) {
 function summarizeImageForList(img) {
     const domain = extractDomain(normalizeText(img.metadata?.url));
     const cleanedTitle = sanitizeSummaryText(img.metadata?.title, domain);
-    const cleanedDesc = sanitizeSummaryText(img.metadata?.desc, domain);
+    const cleanedDesc = sanitizeSummaryText(img.metadata?.desc ?? img.desc, domain);
     const locationLabel = sanitizeSummaryText(extractImageLocationLabel(img));
     const cleanedAltText = sanitizeSummaryText(img.alt_text);
     let main = '(no title/description)';
@@ -1197,6 +1558,9 @@ program
     .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')
@@ -1204,21 +1568,69 @@ program
     await (0, credentials_1.ensureAccessToken)();
     try {
         const useCache = options.cache !== false;
+        const page = parsePositiveIntegerOption(options.page, '--page');
+        const limit = parsePositiveIntegerOption(options.limit, '--limit');
+        const maxPages = parsePositiveIntegerOption(options.maxPages, '--max-pages');
+        const hasDateRange = Boolean(options.date || options.today);
+        const targetDate = hasDateRange
+            ? (options.today ? parseDateOption() : parseDateOption(options.date))
+            : undefined;
         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 aliasQuery = options.photos
             ? 'has:location'
             : options.uploaded
                 ? 'gyazocli_uploads'
                 : undefined;
         if (aliasQuery) {
-            const images = await (0, api_1.searchImages)(aliasQuery, parseInt(options.page, 10), parseInt(options.limit, 10));
+            let images = [];
+            if (targetDate) {
+                const collected = [];
+                for (let searchPage = 1; searchPage <= maxPages; searchPage++) {
+                    const pageImages = await (0, api_1.searchImages)(aliasQuery, searchPage, 100);
+                    if (pageImages.length === 0)
+                        break;
+                    let reachedLimit = false;
+                    for (const img of pageImages) {
+                        const createdAt = new Date(img.created_at);
+                        if (Number.isNaN(createdAt.getTime()))
+                            continue;
+                        if (createdAt > targetDate.end)
+                            continue;
+                        if (createdAt < targetDate.start) {
+                            reachedLimit = true;
+                            break;
+                        }
+                        collected.push(img);
+                    }
+                    if (reachedLimit)
+                        break;
+                }
+                collected.sort((a, b) => {
+                    const ta = new Date(a.created_at).getTime();
+                    const tb = new Date(b.created_at).getTime();
+                    return tb - ta;
+                });
+                const startIndex = (page - 1) * limit;
+                images = collected.slice(startIndex, startIndex + limit);
+            }
+            else {
+                images = await (0, api_1.searchImages)(aliasQuery, page, limit);
+            }
             if (options.json) {
                 console.log(JSON.stringify(images, null, 2));
             }
@@ -1232,6 +1644,50 @@ program
             }
             return;
         }
+        if (targetDate) {
+            let imageIds = [];
+            if (useCache) {
+                imageIds = loadImageIdsFromDateRangeCache(targetDate);
+                if (imageIds.length === 0) {
+                    await warmDateCacheForList(targetDate, maxPages, true);
+                    imageIds = loadImageIdsFromDateRangeCache(targetDate);
+                }
+            }
+            else {
+                imageIds = await warmDateCacheForList(targetDate, maxPages, false);
+            }
+            if (imageIds.length === 0) {
+                console.log(`No images found for ${targetDate.dateKey}.`);
+                return;
+            }
+            let images = imageIds
+                .map(id => (0, storage_1.loadImageCache)(id))
+                .filter((img) => img !== null);
+            images = images.filter((img) => {
+                const createdAt = new Date(img.created_at);
+                if (Number.isNaN(createdAt.getTime()))
+                    return false;
+                return createdAt >= targetDate.start && createdAt <= targetDate.end;
+            });
+            images.sort((a, b) => {
+                const ta = new Date(a.created_at).getTime();
+                const tb = new Date(b.created_at).getTime();
+                return tb - ta;
+            });
+            const startIndex = (page - 1) * limit;
+            const pageImages = images.slice(startIndex, startIndex + limit);
+            if (options.json) {
+                console.log(JSON.stringify(pageImages, null, 2));
+            }
+            else {
+                const imagesForDisplay = await prepareImagesForDisplay(pageImages, {
+                    enrichLocation: true,
+                    useCache,
+                });
+                printListImages(imagesForDisplay);
+            }
+            return;
+        }
         if (options.hour) {
             const parts = options.hour.split('-');
             if (parts.length !== 4) {
@@ -1272,7 +1728,7 @@ program
             }
             return;
         }
-        const images = await (0, api_1.listImages)(parseInt(options.page, 10), parseInt(options.limit, 10));
+        const images = await (0, api_1.listImages)(page, limit);
         if (options.json) {
             console.log(JSON.stringify(images, null, 2));
         }
@@ -1286,6 +1742,7 @@ program
     }
     catch (error) {
         console.error('Error listing images:', error.message);
+        process.exit(1);
     }
 });
 program
@@ -1306,6 +1763,7 @@ program
             console.error('Error: --ocr and --objects cannot be used together.');
             process.exit(1);
         }
+        imageId = requireImageId(imageId);
         let image = options.cache !== false ? (0, storage_1.loadImageCache)(imageId) : null;
         if (!image) {
             image = await (0, api_1.getImageDetail)(imageId);
@@ -1343,6 +1801,43 @@ program
     }
     catch (error) {
         console.error('Error getting image:', error.message);
+        process.exit(1);
+    }
+});
+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 = requireCollectionId(collectionIdInput);
+    const sort = 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 = await (0, api_1.getCollection)(collectionId, { anonymous: Boolean(options.anonymous) });
+        if (options.json) {
+            console.log(JSON.stringify(collection, null, 2));
+            return;
+        }
+        const images = sortCollectionImages(Array.isArray(collection?.images) ? collection.images : [], sort);
+        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);
     }
 });
 program
@@ -1375,6 +1870,7 @@ program
     }
     catch (error) {
         console.error('Error searching images:', error.message);
+        process.exit(1);
     }
 });
 program
@@ -1623,6 +2119,71 @@ program
         process.exit(1);
     }
 });
+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 = resolveRankingRangeOption(options);
+        const requestedLimit = parsePositiveIntegerOption(options.limit, '--limit');
+        const limit = Math.min(requestedLimit, 10);
+        const maxPages = parsePositiveIntegerOption(options.maxPages, '--max-pages');
+        const useCache = options.cache !== false;
+        let dailySummaries = [];
+        if (useCache) {
+            dailySummaries = buildDailySummariesFromImageCache(targetDate);
+            const totalUploads = dailySummaries.reduce((sum, day) => sum + day.imageCount, 0);
+            if (totalUploads === 0) {
+                await warmDateCacheForTags(targetDate, maxPages, true);
+                await warmDateCacheForLocations(targetDate, maxPages, true);
+                dailySummaries = buildDailySummariesFromImageCache(targetDate);
+            }
+            else {
+                const hasMetadata = dailySummaries.some(day => day.apps.length > 0 || day.domains.length > 0 || day.tags.length > 0 || day.locations.length > 0);
+                if (!hasMetadata) {
+                    await warmDateCacheForTags(targetDate, maxPages, true);
+                    await warmDateCacheForLocations(targetDate, maxPages, true);
+                    dailySummaries = buildDailySummariesFromImageCache(targetDate);
+                }
+            }
+        }
+        else {
+            await warmDateCacheForTags(targetDate, maxPages, false);
+            await warmDateCacheForLocations(targetDate, maxPages, false);
+            dailySummaries = buildDailySummariesFromImageCache(targetDate);
+        }
+        if (options.json) {
+            console.log(JSON.stringify({
+                date: targetDate.dateKey,
+                days: dailySummaries.map(day => ({
+                    date: day.date,
+                    image_count: day.imageCount,
+                    apps: day.apps.slice(0, limit),
+                    domains: day.domains.slice(0, limit),
+                    tags: day.tags.slice(0, limit),
+                    locations: day.locations.slice(0, limit),
+                })),
+            }, null, 2));
+            return;
+        }
+        console.log(renderSummaryText({
+            dateKey: targetDate.dateKey,
+            dailySummaries,
+            limit,
+        }));
+    }
+    catch (error) {
+        console.error('Error building summary:', error.message);
+        process.exit(1);
+    }
+});
 program
     .command('stats')
     .description('Show weekly stats summary in Markdown')
@@ -1697,6 +2258,7 @@ 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)')
@@ -1739,13 +2301,12 @@ program
             desc,
             timestamp,
         });
-        console.log(`URL: ${uploaded.permalink_url}`);
-        console.log(`ID: ${uploaded.image_id}`);
-        if (uploaded.created_at) {
-            console.log(`Created at: ${formatCreatedAt(uploaded.created_at)}`);
+        if (options.json) {
+            console.log(JSON.stringify(uploaded, null, 2));
+        }
+        else {
+            console.log(uploaded.permalink_url);
         }
-        console.log(`App: ${options.app || 'gyazocli'}`);
-        console.log(`Desc: ${desc}`);
     }
     catch (error) {
         console.error('Error uploading image:', error.message);
@@ -1900,4 +2461,42 @@ program
         process.exit(1);
     }
 });
-program.parseAsync(process.argv);
+/**
+ * Let the first argument stand on its own when it is unambiguous:
+ * a Gyazo image ID or URL means `get`, an existing file means `upload`.
+ * Anything else is left to commander so unknown commands still report as such.
+ */
+function expandImplicitCommand(argv) {
+    const args = argv.slice(2);
+    const first = args[0];
+    if (!first || first.startsWith('-')) {
+        return argv;
+    }
+    const knownNames = new Set(['help']);
+    for (const command of program.commands) {
+        knownNames.add(command.name());
+        for (const alias of command.aliases()) {
+            knownNames.add(alias);
+        }
+    }
+    if (knownNames.has(first)) {
+        return argv;
+    }
+    let implicitCommand = null;
+    if (normalizeImageId(first)) {
+        // A bare 32-hex ID is ambiguous; treat it as an image.
+        implicitCommand = 'get';
+    }
+    else if (normalizeCollectionId(first)) {
+        // Only the /collections/<id> URL form is unambiguous.
+        implicitCommand = 'collection';
+    }
+    else if (fs_1.default.existsSync(first) && fs_1.default.statSync(first).isFile()) {
+        implicitCommand = 'upload';
+    }
+    if (!implicitCommand) {
+        return argv;
+    }
+    return [...argv.slice(0, 2), implicitCommand, ...args];
+}
+program.parseAsync(expandImplicitCommand(process.argv));

package/docs/ADR/002-caching-strategy.md

@@ -47,6 +47,9 @@ Store cache files under XDG-style user cache location by default, with an enviro
 - `gyazo get <image_id>`:
   - Uses cached detail by default.
   - `--no-cache` forces API fetch and rewrites cache.
+- `gyazo list --date <...>`:
+  - Reads image IDs from hourly index cache files in the target day/month/year range.
+  - If the range has no hourly cache entries, it warms cache from API list pages and then reads from cache.
 - `gyazo sync`:
   - Fetches list pages (`per_page=100`) for a bounded date range.
   - Skips detail fetch when cached record already has `ocr`.
@@ -69,6 +72,11 @@ Store cache files under XDG-style user cache location by default, with an enviro
   - Aggregates upload time bands and rankings of apps/domains/tags from hourly caches.
   - Uses the same hourly metadata extract cache mechanism as ranking commands.
   - If cache data for the target window is absent, warming is triggered once, then summary is built from cache.
+- `gyazo summary`:
+  - Default window is from 8 days ago to yesterday (`7` days).
+  - Outputs day-by-day Markdown sections with `image count` plus rankings of apps/domains/tags/locations.
+  - Uses hourly index cache to discover images per day, then builds rankings from image cache records.
+  - If image-cache metadata is insufficient, warming via list/detail fetch is triggered through ranking warmers.
 
 ## Consequences
 - Cache is portable and independent from the repository working tree.

package/docs/ADR/003-cli-structure.md

@@ -11,7 +11,7 @@ Adopt and document the existing top-level command structure.
 
 ### 1. Program Metadata
 - Binary name: `gyazo`
-- Version: `1.0.0`
+- Version: `0.1.1`
 - Description: `Gyazo Memory CLI for AI Secretary`
 
 ### 2. Commands
@@ -28,8 +28,11 @@ Adopt and document the existing top-level command structure.
     - `-l, --limit <number>` (default: `20`)
     - `-j, --json`
     - `-H, --hour <yyyy-mm-dd-hh>` (reads hourly cache only)
-    - `--photos` (alias of `search has:location`)
-    - `--uploaded` (alias of `search gyazocli_uploads`)
+    - `--date <yyyy|yyyy-mm|yyyy-mm-dd>` (reads date range from hourly cache; warms from API if needed)
+    - `--today` (target today only)
+    - `--max-pages <number>` (default: `100`, used for `--date`/`--today` warming)
+    - `--photos` (alias of `search has:location`, can be combined with `--date`/`--today`)
+    - `--uploaded` (alias of `search gyazocli_uploads`, can be combined with `--date`/`--today`)
     - `--no-cache`
 - `gyazo get <image_id>`
   - Options:
@@ -77,6 +80,18 @@ Adopt and document the existing top-level command structure.
     - `--max-pages <number>` (default: `10`)
     - `-j, --json`
     - `--no-cache`
+- `gyazo summary`
+  - Default range: from 8 days ago to yesterday
+  - Shows day-by-day Markdown sections (`### YYYY-MM-DD`) with:
+    - `image count`
+    - rankings of apps/domains/tags/locations
+  - Options:
+    - `--date <yyyy|yyyy-mm|yyyy-mm-dd>`
+    - `--today` (target today only)
+    - `-l, --limit <number>` (default: `10`, max: `10`)
+    - `--max-pages <number>` (default: `10`)
+    - `-j, --json`
+    - `--no-cache`
 - `gyazo stats`
   - Default range: from 8 days ago to yesterday
   - Default behavior: weekly Markdown summary.
@@ -103,7 +118,8 @@ Adopt and document the existing top-level command structure.
   - Supported types: `json`, `hourly`
 
 ### 3. Output and Behavior Notes
-- `-j, --json` is available on `config get`, `list`, `get`, `search`, `apps`, `domains`, `tags`, and `locations`.
+- `-j, --json` is available on `config get`, `list`, `get`, `search`, `apps`, `domains`, `tags`, `locations`, and `summary`.
+- `summary` default output is Markdown with headings (`## Gyazo Summary`, `### YYYY-MM-DD`) and nested bullet lists.
 - There are no global `--plain` or `--verbose` flags in current implementation.
 - Authenticated commands call token resolution before API access.
 

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@yuiseki/gyazocli",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "Gyazo Memory CLI for AI Secretary",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yuiseki/gyazocli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yuiseki/gyazocli/issues"
+  },
+  "homepage": "https://github.com/yuiseki/gyazocli#readme",
   "main": "dist/index.js",
   "bin": {
     "gyazo": "dist/index.js"
@@ -31,6 +39,7 @@
     "axios": "^1.13.5",
     "commander": "^14.0.3",
     "dotenv": "^17.3.1",
+    "form-data": "^4.0.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {