@yuiseki/gyazocli 0.0.1

package/dist/storage.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCacheDir = getCacheDir;
+exports.getImagePath = getImagePath;
+exports.getSearchImagePath = getSearchImagePath;
+exports.getHourlyPath = getHourlyPath;
+exports.saveImageCache = saveImageCache;
+exports.loadImageCache = loadImageCache;
+exports.saveSearchImageCache = saveSearchImageCache;
+exports.loadSearchImageCache = loadSearchImageCache;
+exports.saveHourlyCache = saveHourlyCache;
+exports.loadHourlyCache = loadHourlyCache;
+exports.saveHourlyMetadataCache = saveHourlyMetadataCache;
+exports.loadHourlyMetadataCache = loadHourlyMetadataCache;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+function getCacheDir() {
+    if (process.env.GYAZO_CACHE_DIR) {
+        return process.env.GYAZO_CACHE_DIR;
+    }
+    const cacheBase = process.env.XDG_CACHE_HOME || path_1.default.join(os_1.default.homedir(), '.cache');
+    const dir = path_1.default.join(cacheBase, 'gyazocli');
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+function getImagePath(imageId) {
+    const prefix1 = imageId[0] || '_';
+    const prefix2 = imageId[1] || '_';
+    const dir = path_1.default.join(getCacheDir(), 'images', prefix1, prefix2);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    return path_1.default.join(dir, `${imageId}.json`);
+}
+function getSearchImagePath(imageId) {
+    const prefix1 = imageId[0] || '_';
+    const prefix2 = imageId[1] || '_';
+    const dir = path_1.default.join(getCacheDir(), 'search_images', prefix1, prefix2);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    return path_1.default.join(dir, `${imageId}.json`);
+}
+function getHourlyPath(year, month, day, hour) {
+    const dir = path_1.default.join(getCacheDir(), 'hourly', year, month, day);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    return path_1.default.join(dir, `${hour}.json`);
+}
+function getHourlyMetadataPath(kind, year, month, day, hour) {
+    const dir = path_1.default.join(getCacheDir(), 'hourly', year, month, day);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    return path_1.default.join(dir, `${hour}-${kind}.json`);
+}
+function saveImageCache(imageId, data) {
+    const filePath = getImagePath(imageId);
+    fs_1.default.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+function loadImageCache(imageId) {
+    const filePath = getImagePath(imageId);
+    if (fs_1.default.existsSync(filePath)) {
+        return JSON.parse(fs_1.default.readFileSync(filePath, 'utf-8'));
+    }
+    return null;
+}
+function saveSearchImageCache(imageId, data) {
+    const filePath = getSearchImagePath(imageId);
+    fs_1.default.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+function loadSearchImageCache(imageId) {
+    const filePath = getSearchImagePath(imageId);
+    if (fs_1.default.existsSync(filePath)) {
+        return JSON.parse(fs_1.default.readFileSync(filePath, 'utf-8'));
+    }
+    return null;
+}
+function saveHourlyCache(year, month, day, hour, imageIds) {
+    const filePath = getHourlyPath(year, month, day, hour);
+    fs_1.default.writeFileSync(filePath, JSON.stringify(imageIds, null, 2), 'utf-8');
+}
+function loadHourlyCache(year, month, day, hour) {
+    const filePath = getHourlyPath(year, month, day, hour);
+    if (fs_1.default.existsSync(filePath)) {
+        return JSON.parse(fs_1.default.readFileSync(filePath, 'utf-8'));
+    }
+    return null;
+}
+function saveHourlyMetadataCache(kind, year, month, day, hour, valuesByImageId) {
+    const filePath = getHourlyMetadataPath(kind, year, month, day, hour);
+    fs_1.default.writeFileSync(filePath, JSON.stringify(valuesByImageId, null, 2), 'utf-8');
+}
+function loadHourlyMetadataCache(kind, year, month, day, hour) {
+    const filePath = getHourlyMetadataPath(kind, year, month, day, hour);
+    if (fs_1.default.existsSync(filePath)) {
+        return JSON.parse(fs_1.default.readFileSync(filePath, 'utf-8'));
+    }
+    return null;
+}

package/docs/ADR/001-credentials.md

@@ -0,0 +1,38 @@
+# ADR 001: Credential Management and Configuration
+
+## Status
+Accepted
+
+## Context
+`gyazocli` needs a credential flow that works in both local shell usage and automation. The implementation currently supports loading values from environment variables and persisting an access token in a local config file.
+
+## Decision
+Use `GYAZO_ACCESS_TOKEN` as the primary runtime credential, with a local fallback file for convenience.
+
+### 1. Supported Environment Variables
+- `GYAZO_ACCESS_TOKEN`: Personal access token used for API requests.
+- `GYAZO_CLIENT_ID`: Parsed from env for future OAuth use (not used by current commands).
+- `GYAZO_CLIENT_SECRET`: Parsed from env for future OAuth use (not used by current commands).
+- `GYAZO_CACHE_DIR`: Optional cache directory override (used by storage logic).
+
+### 2. `.env` Loading Behavior
+- `dotenv` is used via `dotenv.config()`.
+- `.env` is loaded from the current working directory by default.
+- If the same key is already set in process environment, that value takes precedence.
+
+### 3. Local Stored Token
+- File path: `~/.config/gyazo/credentials.json`
+- Supported key for CLI config commands: `token`
+- `gyazo config set token <value>` stores `GYAZO_ACCESS_TOKEN` in the file.
+- `gyazo config get token` prints a masked token value.
+
+### 4. Access Token Resolution Order
+When an authenticated command runs:
+1. `GYAZO_ACCESS_TOKEN` from environment/config object
+2. Stored token from `~/.config/gyazo/credentials.json`
+3. Exit with an error and instructions
+
+## Consequences
+- Token management works without requiring shell profile edits.
+- CI and non-interactive usage can rely on environment variables only.
+- OAuth client fields are documented but currently unused by CLI commands.

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

@@ -0,0 +1,77 @@
+# ADR 002: Caching Strategy and Storage Structure
+
+## Status
+Accepted
+
+## Context
+`gyazocli` caches image detail and hourly indices on local disk so repeated lookups avoid unnecessary API calls and historical lookups can be served quickly.
+
+## Decision
+Store cache files under XDG-style user cache location by default, with an environment override.
+
+### 1. Cache Root
+`getCacheDir()` resolves cache root as:
+1. `GYAZO_CACHE_DIR` (if set)
+2. `${XDG_CACHE_HOME}/gyazocli` (if `XDG_CACHE_HOME` is set)
+3. `~/.cache/gyazocli`
+
+### 2. Image Cache Layout
+- Path pattern: `<cacheRoot>/images/<firstChar>/<secondChar>/<imageId>.json`
+- Example: `~/.cache/gyazocli/images/a/1/a1b2c3d4.json`
+- Purpose: Avoid a single large flat directory.
+
+### 3. Hourly Index Layout
+- Path pattern: `<cacheRoot>/hourly/<YYYY>/<MM>/<DD>/<HH>.json`
+- File content: JSON array of image IDs for that hour.
+- Used by `gyazo list --hour <yyyy-mm-dd-hh>`.
+
+### 4. Hourly Metadata Extract Cache Layout
+- Path patterns:
+  - `<cacheRoot>/hourly/<YYYY>/<MM>/<DD>/<HH>-apps.json`
+  - `<cacheRoot>/hourly/<YYYY>/<MM>/<DD>/<HH>-domains.json`
+  - `<cacheRoot>/hourly/<YYYY>/<MM>/<DD>/<HH>-tags.json`
+  - `<cacheRoot>/hourly/<YYYY>/<MM>/<DD>/<HH>-locations.json`
+- File content:
+  - JSON object keyed by `image_id`.
+  - Value is string array of extracted metadata tokens for that command.
+  - Example:
+    - `apps`: `{ "<imageId>": ["Chrome"] }`
+    - `domains`: `{ "<imageId>": ["x.com"] }`
+    - `tags`: `{ "<imageId>": ["ゆいせきのコーデ", "ゆいせきの自撮り"] }`
+    - `locations`: `{ "<imageId>": ["東京都台東区竜泉"] }`
+- Purpose:
+  - Avoid repeated full image-cache scans when computing rankings.
+  - Preserve negative results (`[]`) per image so commands do not re-fetch detail repeatedly.
+
+### 5. Cache Update Behavior in Commands
+- `gyazo get <image_id>`:
+  - Uses cached detail by default.
+  - `--no-cache` forces API fetch and rewrites cache.
+- `gyazo sync`:
+  - Fetches list pages (`per_page=100`) for a bounded date range.
+  - Skips detail fetch when cached record already has `ocr`.
+  - Writes/merges hourly index files.
+- `gyazo apps`, `gyazo domains`, `gyazo tags`, `gyazo locations`:
+  - Default target range is from 8 days ago to yesterday.
+  - `--today` targets only today.
+  - `--date` can target a specific day/month/year.
+  - With default cache mode:
+    - Read ranking from hourly metadata extract caches for fast aggregation.
+    - If `<HH>-*.json` is missing but `<HH>.json` exists, build it once from image cache and persist.
+    - If the target range has no hourly cache data, run API-based warming once, then read from cache.
+  - With `--no-cache`:
+    - Force API-based warming by scanning list pages (`per_page=100`) in the target date range.
+    - Update both hourly image index (`<HH>.json`) and hourly metadata extract caches (`<HH>-*.json`).
+    - Ranking is computed from warmed image cache data for that run (no historical cache merge).
+- `gyazo stats`:
+  - Default window is from 8 days ago to yesterday (`7` days), output is Markdown.
+  - Section rows are rendered as bullet lists (`- <label>: <count>`), not tables.
+  - 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.
+
+## Consequences
+- Cache is portable and independent from the repository working tree.
+- Large historical datasets remain manageable on filesystem.
+- Ranking commands become significantly faster on repeated runs due to hourly extracted metadata cache.
+- Cache freshness depends on command behavior (`get --no-cache`, `sync`, and ranking command warming).

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

@@ -0,0 +1,112 @@
+# ADR 003: CLI Command Structure and Interface
+
+## Status
+Accepted
+
+## Context
+The current `gyazocli` implementation uses flat top-level commands (not nested under `images`). Documentation should reflect the command tree implemented in `src/index.ts`.
+
+## Decision
+Adopt and document the existing top-level command structure.
+
+### 1. Program Metadata
+- Binary name: `gyazo`
+- Version: `1.0.0`
+- Description: `Gyazo Memory CLI for AI Secretary`
+
+### 2. Commands
+- `gyazo config set <key> <value>`
+  - Currently supported key: `token`
+- `gyazo config get <key>`
+  - `token` is masked
+  - `me` fetches `/api/users/me`
+  - Options:
+    - `-j, --json`
+- `gyazo list` (alias: `gyazo ls`)
+  - Options:
+    - `-p, --page <number>` (default: `1`)
+    - `-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`)
+    - `--no-cache`
+- `gyazo get <image_id>`
+  - Options:
+    - `-j, --json`
+    - `--ocr`
+    - `--objects`
+    - `--no-cache`
+- `gyazo search [query]`
+  - Options:
+    - `-j, --json`
+    - `--no-cache`
+- `gyazo apps`
+  - Default range: from 8 days ago to yesterday
+  - 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 domains`
+  - Default range: from 8 days ago to yesterday
+  - 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 tags`
+  - Default range: from 8 days ago to yesterday
+  - 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 locations`
+  - Default range: from 8 days ago to yesterday
+  - 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.
+  - Section rows are rendered as bullet lists (`- <label>: <count>`) for terminal readability.
+  - Options:
+    - `--date <yyyy|yyyy-mm|yyyy-mm-dd>` (window end date anchor; default: yesterday)
+    - `--days <number>` (default: `7`)
+    - `--top <number>` (default: `10`)
+    - `--max-pages <number>` (default: `10`)
+    - `--no-cache`
+- `gyazo upload [path]`
+  - Options:
+    - `--title <title>`
+    - `--app <app>` (default: `gyazocli`)
+    - `--url <url>`
+    - `--timestamp <unix_timestamp>`
+    - `--desc <desc>` (`#gyazocli_uploads` is always appended)
+- `gyazo sync`
+  - Options:
+    - `--days <number>` (default: `1`, used when `--date` is omitted)
+    - `--date <yyyy|yyyy-mm|yyyy-mm-dd>`
+    - `--max-pages <number>` (default: `10`)
+- `gyazo import <type> <dir>`
+  - Supported types: `json`, `hourly`
+
+### 3. Output and Behavior Notes
+- `-j, --json` is available on `config get`, `list`, `get`, `search`, `apps`, `domains`, `tags`, and `locations`.
+- There are no global `--plain` or `--verbose` flags in current implementation.
+- Authenticated commands call token resolution before API access.
+
+## Consequences
+- Docs now match the command UX shipped in code.
+- Users can rely on CLI help output and docs without cross-project noise.

package/docs/API/gyazo_api.md

@@ -0,0 +1,66 @@
+# Gyazo API
+
+Gyazo provides a REST API to access user images and metadata including OCR and object recognition results.
+
+## Base URL
+
+`https://api.gyazo.com/api`
+
+## Authentication
+
+Authentication is performed using an OAuth2 Access Token.
+
+**Header:** `Authorization: Bearer {access_token}`
+
+---
+
+## Endpoints
+
+### 1. List Images
+`GET /images`
+
+Fetch metadata for the user's images.
+
+**Parameters:**
+- `page` (int): Page number.
+- `per_page` (int): Number of items per page (Max: 100).
+
+### 2. Search Images
+`GET /search`
+
+Search for images using queries.
+
+**Parameters:**
+- `query` (string): Search query (e.g., `date:YYYY-MM-DD`).
+- `page` (int): Page number.
+- `per` (int): Number of items per page.
+
+### 3. Get Image Detail
+`GET /images/{image_id}`
+
+Fetch detailed information for a specific image, including OCR and localized object annotations.
+
+---
+
+## Data Models
+
+### Image Object
+- `image_id`: Unique identifier.
+- `permalink_url`: Gyazo page URL.
+- `url`: Direct image URL.
+- `type`: Image type (e.g., `png`, `jpg`).
+- `created_at`: Creation timestamp (ISO 8601).
+- `ocr`: OCR results (description and locale).
+- `metadata`:
+  - `title`: Window title at the time of capture.
+  - `url`: Source URL of the capture.
+  - `app`: Application name.
+  - `links`: Extracted link keywords (used as tags in this CLI).
+  - `exif_address`: Geolocation address from EXIF.
+
+---
+
+## Rate Limiting
+
+If you exceed the rate limit, the API returns a `429 Too Many Requests` status code.
+Check the `Retry-After` header for the number of seconds to wait before retrying.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@yuiseki/gyazocli",
+  "version": "0.0.1",
+  "description": "Gyazo Memory CLI for AI Secretary",
+  "main": "dist/index.js",
+  "bin": {
+    "gyazo": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "build": "npx tsc",
+    "prepack": "npm run build",
+    "test": "npm run build && vitest run",
+    "test:watch": "vitest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "axios": "^1.13.5",
+    "commander": "^14.0.3",
+    "dotenv": "^17.3.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}