@orangemust/unsplash-cli 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,33 @@
+# unsplash-cli
+
+Agent notes for `@orangemust/unsplash-cli`.
+
+## Commands
+
+```bash
+unsplash auth status --json
+unsplash auth set --stdin          # pbpaste | unsplash auth set --stdin
+unsplash auth clear
+unsplash search "<query>" --json
+unsplash search "<query>" --download 2 --out-dir <dir> --json
+unsplash download <id|url> --out <file> --json
+```
+
+## Rules
+
+- Never print, echo or log the Access Key.
+- Key lives in macOS Keychain (service `unsplash-cli`); `UNSPLASH_ACCESS_KEY` is an env override for CI only.
+- Do not create `.env` files for this project.
+- `--json` is the agent-facing output; human output is for terminals.
+- Downloads write a `<photo-id>.json` sidecar and trigger Unsplash download tracking automatically.
+- Keep attribution (`Photo by <name> on Unsplash`) when an image is published.
+- 401/403/429 are not retried automatically; report the error.
+- Tests: `npm test` (local mock API, no Keychain/network).
+
+## Build
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mack-peng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# @orangemust/unsplash-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Search and download [Unsplash](https://unsplash.com) photos from the command line.
+
+- Search with orientation / color / order filters
+- Download the original or a specific size
+- Writes a `<photo-id>.json` sidecar with photographer, source page and license
+- Tracks downloads as required by the Unsplash API guidelines
+- **Access Key stored in macOS Keychain** — never in `.env`, project files or shell history
+
+## Install
+
+```bash
+# from this directory
+npm install
+npm run build
+npm link
+
+# or after publishing
+npm install -g @orangemust/unsplash-cli
+```
+
+> `unsplash-cli` on npm is an unrelated, unmaintained 2015 package. This project uses the scoped name `@orangemust/unsplash-cli`; the command is `unsplash` (alias `unsplash-cli`).
+
+## Authentication
+
+Get an Access Key from <https://unsplash.com/oauth/applications> (New application → Access Key, not the Secret Key).
+
+Store it in the macOS Keychain:
+
+```bash
+unsplash auth set
+# or paste from clipboard without putting the key in shell history
+pbpaste | unsplash auth set --stdin
+```
+
+Check status without printing the key:
+
+```bash
+unsplash auth status
+# Configured: yes
+# Source: macOS Keychain (service: unsplash-cli)
+```
+
+Remove it:
+
+```bash
+unsplash auth clear
+```
+
+The key is stored as a generic password with service `unsplash-cli` and account `default`. It is read with the macOS `security` command; the first read may show a Keychain access prompt — choose **Always Allow** if you do not want to see it again.
+
+For CI or non-macOS environments, set `UNSPLASH_ACCESS_KEY`; it takes precedence over Keychain storage.
+
+## Usage
+
+```bash
+# Search
+unsplash search "minimal desk" --per-page 6
+unsplash search "minimal desk" --orientation portrait --color white --json
+
+# Download one photo by id or Unsplash URL
+unsplash download abc123XYZ --out ./assets/desk.jpg
+unsplash download https://unsplash.com/photos/some-slug-abc123XYZ --out-dir ./assets
+
+# Search and download the first two results
+unsplash search "minimal desk" --download 2 --out-dir ./assets/refs
+```
+
+### Options
+
+`search`:
+
+- `--per-page N` — 1–30, default 6
+- `--page N` — default 1
+- `--orientation landscape|portrait|squarish`
+- `--color black_and_white|black|white|yellow|orange|red|purple|magenta|green|teal|blue`
+- `--order-by relevant|latest`
+- `--download N` — requires `--out-dir`
+- `--out-dir DIR`
+- `--size raw|full|regular|small|thumb` — default `full`
+- `--json`
+
+`download`:
+
+- `--out FILE` or `--out-dir DIR`
+- `--size raw|full|regular|small|thumb` — default `full`
+- `--json`
+
+## Output and compliance
+
+Human output lists the photo id, dimensions, description, photographer credit and source page. `--json` returns a compact object for agents.
+
+Each download saves the image plus a sidecar:
+
+```json
+{
+  "provider": "unsplash",
+  "id": "abc123XYZ",
+  "photographer": { "name": "Jane Doe", "profile_url": "https://unsplash.com/@jane?utm_source=unsplash-cli&utm_medium=referral" },
+  "photo_page": "https://unsplash.com/photos/abc123XYZ?utm_source=unsplash-cli&utm_medium=referral",
+  "attribution": "Photo by Jane Doe on Unsplash (...)",
+  "download_tracked": true,
+  "license": "https://unsplash.com/license"
+}
+```
+
+When publishing an image, keep the attribution and link. The Unsplash License allows free commercial use, but does not allow selling unmodified copies or building a competing image service.
+
+The CLI calls Unsplash's `download_location` endpoint after saving an image. If tracking fails it warns but keeps the file. API errors (401/403/429) are reported without retrying.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+node bin/unsplash.js --help
+```
+
+Tests use a local mock API (`UNSPLASH_API_BASE`) and never touch the real Keychain or network.
+
+## License
+
+MIT

package/bin/unsplash.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+const { main } = require('../dist/index');
+
+main().catch((error) => {
+  console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});

package/dist/api.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsplashApi = exports.ApiError = void 0;
+class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'ApiError';
+    }
+}
+exports.ApiError = ApiError;
+class UnsplashApi {
+    key;
+    base;
+    lastRate = { limit: null, remaining: null };
+    constructor(key, base = process.env.UNSPLASH_API_BASE || 'https://api.unsplash.com') {
+        this.key = key;
+        this.base = base.replace(/\/+$/, '');
+    }
+    headers() {
+        return {
+            Authorization: `Client-ID ${this.key}`,
+            'Accept-Version': 'v1',
+        };
+    }
+    updateRate(response) {
+        this.lastRate = {
+            limit: response.headers.get('x-ratelimit-limit') ?? this.lastRate.limit,
+            remaining: response.headers.get('x-ratelimit-remaining') ?? this.lastRate.remaining,
+        };
+    }
+    async request(path, params = {}) {
+        const url = new URL(this.base + path);
+        for (const [name, value] of Object.entries(params)) {
+            if (value !== undefined && value !== '')
+                url.searchParams.set(name, String(value));
+        }
+        const response = await fetch(url, { headers: this.headers() });
+        this.updateRate(response);
+        if (!response.ok)
+            throw await toApiError(response);
+        return (await response.json());
+    }
+    search(query, options = {}) {
+        return this.request('/search/photos', {
+            query,
+            per_page: options.perPage,
+            page: options.page,
+            orientation: options.orientation,
+            color: options.color,
+            order_by: options.orderBy,
+        });
+    }
+    photo(id) {
+        return this.request(`/photos/${encodeURIComponent(id)}`);
+    }
+    random() {
+        return this.request('/photos/random');
+    }
+    async track(downloadLocation) {
+        if (!downloadLocation)
+            return false;
+        try {
+            const response = await fetch(downloadLocation, { headers: this.headers() });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    async fetchImage(url) {
+        const response = await fetch(url);
+        if (!response.ok)
+            throw new Error(`Image download failed (HTTP ${response.status}).`);
+        return {
+            buffer: Buffer.from(await response.arrayBuffer()),
+            contentType: response.headers.get('content-type') ?? '',
+        };
+    }
+}
+exports.UnsplashApi = UnsplashApi;
+async function toApiError(response) {
+    let detail = '';
+    try {
+        const body = (await response.json());
+        detail = body.errors?.join('; ') || body.error || '';
+    }
+    catch {
+        // ignore non-JSON error bodies
+    }
+    if (response.status === 401) {
+        return new ApiError(401, 'Invalid Unsplash Access Key (401). Run `unsplash auth set` to update it.');
+    }
+    if (response.status === 403 || response.status === 429) {
+        return new ApiError(response.status, `Unsplash rate limit reached (${response.status}). Try again later.`);
+    }
+    return new ApiError(response.status, `Unsplash API error ${response.status}${detail ? `: ${detail}` : ''}.`);
+}

package/dist/auth.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keychainSupported = keychainSupported;
+exports.keychainStatus = keychainStatus;
+exports.readKeychainKey = readKeychainKey;
+exports.writeKeychainKey = writeKeychainKey;
+exports.deleteKeychainKey = deleteKeychainKey;
+exports.envKey = envKey;
+exports.resolveKey = resolveKey;
+exports.readSecret = readSecret;
+const node_child_process_1 = require("node:child_process");
+const node_os_1 = require("node:os");
+const node_readline_1 = require("node:readline");
+const SERVICE = 'unsplash-cli';
+const ACCOUNT = 'default';
+function keychainSupported() {
+    return (0, node_os_1.platform)() === 'darwin';
+}
+function keychainStatus() {
+    if (!keychainSupported())
+        return 'unsupported';
+    try {
+        (0, node_child_process_1.execFileSync)('security', ['find-generic-password', '-s', SERVICE, '-a', ACCOUNT], {
+            stdio: 'ignore',
+        });
+        return 'configured';
+    }
+    catch {
+        return 'missing';
+    }
+}
+function readKeychainKey() {
+    if (!keychainSupported())
+        return null;
+    try {
+        const key = (0, node_child_process_1.execFileSync)('security', ['find-generic-password', '-s', SERVICE, '-a', ACCOUNT, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        return key || null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeKeychainKey(key) {
+    if (!keychainSupported()) {
+        throw new Error('macOS Keychain is not available on this platform. Use UNSPLASH_ACCESS_KEY instead.');
+    }
+    (0, node_child_process_1.execFileSync)('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', ACCOUNT, '-w', key], { stdio: 'ignore' });
+}
+function deleteKeychainKey() {
+    if (!keychainSupported())
+        return false;
+    try {
+        (0, node_child_process_1.execFileSync)('security', ['delete-generic-password', '-s', SERVICE, '-a', ACCOUNT], {
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function envKey() {
+    const key = process.env.UNSPLASH_ACCESS_KEY?.trim();
+    return key || null;
+}
+function resolveKey() {
+    const env = envKey();
+    if (env)
+        return { key: env, source: 'env' };
+    const keychain = readKeychainKey();
+    if (keychain)
+        return { key: keychain, source: 'keychain' };
+    throw new Error('Unsplash Access Key is not configured. Run `unsplash auth set`.');
+}
+async function readSecret(label, forceStdin = false) {
+    if (forceStdin || !process.stdin.isTTY) {
+        if (forceStdin && process.stdin.isTTY) {
+            throw new Error('--stdin requires piped input. Pipe the key or omit --stdin.');
+        }
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(Buffer.from(chunk));
+        return Buffer.concat(chunks).toString('utf8').trim();
+    }
+    process.stdout.write(label);
+    return new Promise((resolve, reject) => {
+        const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stdout, terminal: true });
+        rl._writeToOutput = () => { };
+        rl.question('', (value) => {
+            rl.close();
+            process.stdout.write('\n');
+            resolve(value.trim());
+        });
+        rl.on('SIGINT', () => {
+            rl.close();
+            process.stdout.write('\n');
+            reject(new Error('Cancelled.'));
+        });
+    });
+}

package/dist/index.js

@@ -0,0 +1,335 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+const api_1 = require("./api");
+const auth_1 = require("./auth");
+const photos_1 = require("./photos");
+const HELP = `unsplash — search and download Unsplash photos
+
+Usage:
+  unsplash auth set [--stdin] [--skip-verify]
+  unsplash auth status [--json]
+  unsplash auth clear
+  unsplash search "<query>" [options]
+  unsplash download <id|url> [options]
+  unsplash --version
+
+Security:
+  The Access Key is stored in the macOS Keychain (service "unsplash-cli").
+  It is never written to .env or project files. The UNSPLASH_ACCESS_KEY
+  environment variable overrides Keychain storage for CI.
+
+Run \`unsplash <command> --help\` for command options.`;
+const AUTH_HELP = `Usage:
+  unsplash auth set [--stdin] [--skip-verify] [--json]
+  unsplash auth status [--json]
+  unsplash auth clear [--json]
+
+  set      Store the Access Key in macOS Keychain (prompts, input hidden).
+           Use --stdin to read from a pipe: pbpaste | unsplash auth set --stdin
+  status   Show whether a key is configured; never prints the key.
+  clear    Remove the Keychain entry.`;
+const SEARCH_HELP = `Usage:
+  unsplash search "<query>" [options]
+
+Options:
+  --per-page N        Results per page (1-30, default 6)
+  --page N            Page number (default 1)
+  --orientation X     landscape | portrait | squarish
+  --color X           black_and_white, black, white, yellow, orange,
+                      red, purple, magenta, green, teal, blue
+  --order-by X        relevant | latest (default relevant)
+  --download N        Download the first N results (requires --out-dir)
+  --out-dir DIR       Directory for downloaded images
+  --size X            raw | full | regular | small | thumb (default full)
+  --json              Machine-readable JSON
+  --help              Show this help`;
+const DOWNLOAD_HELP = `Usage:
+  unsplash download <id|url> [options]
+
+Options:
+  --out FILE          Exact output file path
+  --out-dir DIR       Directory; file is named <photo-id>.<ext>
+  --size X            raw | full | regular | small | thumb (default full)
+  --json              Machine-readable JSON
+  --help              Show this help
+
+Each download writes a <photo-id>.json sidecar with photographer,
+source page, license and download-tracking status.`;
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+        console.log(HELP);
+        return;
+    }
+    if (argv[0] === '--version' || argv[0] === '-v') {
+        console.log(version());
+        return;
+    }
+    const command = argv.shift();
+    switch (command) {
+        case 'auth':
+            await runAuth(argv);
+            return;
+        case 'search':
+            await runSearch(argv);
+            return;
+        case 'download':
+            await runDownload(argv);
+            return;
+        default:
+            throw new Error(`Unknown command: ${command}. Run \`unsplash --help\`.`);
+    }
+}
+async function runAuth(argv) {
+    const sub = argv[0];
+    if (!sub || sub === '--help' || sub === '-h' || argv.includes('--help') || argv.includes('-h')) {
+        console.log(AUTH_HELP);
+        return;
+    }
+    if (sub === 'set') {
+        const { values } = (0, node_util_1.parseArgs)({
+            args: argv.slice(1),
+            options: {
+                stdin: { type: 'boolean' },
+                'skip-verify': { type: 'boolean' },
+                json: { type: 'boolean' },
+            },
+            allowPositionals: false,
+            strict: true,
+        });
+        const key = await (0, auth_1.readSecret)('Unsplash Access Key: ', Boolean(values.stdin));
+        if (!key)
+            throw new Error('No key provided.');
+        if (!values['skip-verify']) {
+            const api = new api_1.UnsplashApi(key);
+            try {
+                await api.random();
+            }
+            catch (error) {
+                if (error instanceof api_1.ApiError && error.status === 403) {
+                    console.error('warning: key could not be verified because the rate limit is exhausted; saving anyway.');
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        (0, auth_1.writeKeychainKey)(key);
+        if (values.json) {
+            console.log(JSON.stringify({ configured: true, source: 'keychain' }, null, 2));
+        }
+        else {
+            console.log('Saved Unsplash Access Key to macOS Keychain (service: unsplash-cli).');
+        }
+        return;
+    }
+    if (sub === 'status') {
+        const { values } = (0, node_util_1.parseArgs)({
+            args: argv.slice(1),
+            options: { json: { type: 'boolean' } },
+            allowPositionals: false,
+            strict: true,
+        });
+        const env = Boolean((0, auth_1.envKey)());
+        const keychain = (0, auth_1.keychainStatus)();
+        const source = env ? 'env' : keychain === 'configured' ? 'keychain' : null;
+        const configured = source !== null;
+        if (values.json) {
+            console.log(JSON.stringify({ configured, source, env, keychain }, null, 2));
+            return;
+        }
+        console.log(`Configured: ${configured ? 'yes' : 'no'}`);
+        if (configured) {
+            console.log(`Source: ${source === 'env' ? 'UNSPLASH_ACCESS_KEY environment variable' : 'macOS Keychain (service: unsplash-cli)'}`);
+        }
+        console.log(`Keychain: ${keychain}`);
+        console.log(`Environment: ${env ? 'set' : 'not set'}`);
+        if (!configured)
+            console.log('\nRun: unsplash auth set');
+        return;
+    }
+    if (sub === 'clear') {
+        const { values } = (0, node_util_1.parseArgs)({
+            args: argv.slice(1),
+            options: { json: { type: 'boolean' } },
+            allowPositionals: false,
+            strict: true,
+        });
+        const removed = (0, auth_1.deleteKeychainKey)();
+        if (values.json) {
+            console.log(JSON.stringify({ cleared: removed }, null, 2));
+            return;
+        }
+        console.log(removed
+            ? 'Removed Unsplash Access Key from macOS Keychain.'
+            : 'No Keychain entry found.');
+        if ((0, auth_1.envKey)()) {
+            console.error('warning: UNSPLASH_ACCESS_KEY is still set in this environment and will take precedence.');
+        }
+        return;
+    }
+    throw new Error(`Unknown auth command: ${sub}. Run \`unsplash auth --help\`.`);
+}
+async function runSearch(argv) {
+    const { values, positionals } = (0, node_util_1.parseArgs)({
+        args: argv,
+        options: {
+            'per-page': { type: 'string' },
+            page: { type: 'string' },
+            orientation: { type: 'string' },
+            color: { type: 'string' },
+            'order-by': { type: 'string' },
+            download: { type: 'string' },
+            'out-dir': { type: 'string' },
+            size: { type: 'string' },
+            json: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    if (values.help) {
+        console.log(SEARCH_HELP);
+        return;
+    }
+    const query = positionals.join(' ').trim();
+    if (!query)
+        throw new Error('search requires a query.');
+    const perPage = intOption(values['per-page'], '--per-page', 6, 1, 30);
+    const page = intOption(values.page, '--page', 1, 1, Number.MAX_SAFE_INTEGER);
+    const downloadCount = intOption(values.download, '--download', 0, 0, 30);
+    const size = sizeOption(values.size);
+    const outDir = values['out-dir'];
+    if (downloadCount > 0 && !outDir)
+        throw new Error('--out-dir is required with --download.');
+    const { key } = (0, auth_1.resolveKey)();
+    const api = new api_1.UnsplashApi(key);
+    const data = await api.search(query, {
+        perPage,
+        page,
+        orientation: values.orientation,
+        color: values.color,
+        orderBy: values['order-by'],
+    });
+    const results = data.results.map((photo) => (0, photos_1.compactPhoto)(photo, query));
+    const downloads = [];
+    if (downloadCount > 0 && outDir) {
+        for (const result of results.slice(0, downloadCount)) {
+            downloads.push(await (0, photos_1.downloadPhoto)(api, result.id, { outDir, size }));
+        }
+    }
+    if (values.json) {
+        console.log(JSON.stringify({
+            query,
+            page,
+            total: data.total,
+            totalPages: data.total_pages,
+            rate: api.lastRate,
+            results,
+            ...(downloads.length ? { downloads } : {}),
+        }, null, 2));
+        return;
+    }
+    printSearch({
+        query,
+        page,
+        total: data.total,
+        totalPages: data.total_pages,
+        rate: api.lastRate,
+        results,
+        downloads,
+    });
+}
+async function runDownload(argv) {
+    const { values, positionals } = (0, node_util_1.parseArgs)({
+        args: argv,
+        options: {
+            out: { type: 'string' },
+            'out-dir': { type: 'string' },
+            size: { type: 'string' },
+            json: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    if (values.help) {
+        console.log(DOWNLOAD_HELP);
+        return;
+    }
+    const ref = positionals[0];
+    if (!ref)
+        throw new Error('download requires a photo id or URL.');
+    if (!values.out && !values['out-dir']) {
+        throw new Error('download requires --out or --out-dir.');
+    }
+    const size = sizeOption(values.size);
+    const { key } = (0, auth_1.resolveKey)();
+    const api = new api_1.UnsplashApi(key);
+    const record = await (0, photos_1.downloadPhoto)(api, ref, {
+        out: values.out,
+        outDir: values['out-dir'],
+        size,
+    });
+    if (values.json) {
+        console.log(JSON.stringify(record, null, 2));
+        return;
+    }
+    console.log(`File: ${record.file}`);
+    if (record.sidecar)
+        console.log(`Sidecar: ${record.sidecar}`);
+    console.log(`Size: ${record.width}x${record.height} (${record.size})`);
+    console.log(`Credit: ${record.attribution}`);
+    console.log(`Page: ${record.photo_page}`);
+}
+function printSearch(result) {
+    console.log(`${result.total} results for "${result.query}" (page ${result.page}/${result.totalPages})`);
+    result.results.forEach((photo, index) => {
+        console.log(`\n${index + 1}. ${photo.id}  ${photo.width}x${photo.height}`);
+        console.log(`   ${photo.description || '(no description)'}`);
+        console.log(`   ${photo.attribution}`);
+        console.log(`   ${photo.photo_page}`);
+    });
+    if (result.downloads.length) {
+        console.log('\nDownloaded:');
+        result.downloads.forEach((item) => {
+            console.log(`- ${item.file}  (${item.attribution})`);
+        });
+    }
+    console.log(`\nRate: ${result.rate.remaining ?? '?'}/${result.rate.limit ?? '?'} remaining`);
+}
+function intOption(value, flag, fallback, min, max) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+        throw new Error(`${flag} must be an integer between ${min} and ${max}.`);
+    }
+    return parsed;
+}
+function sizeOption(value) {
+    const size = (value ?? 'full');
+    if (!photos_1.SIZES.includes(size)) {
+        throw new Error(`--size must be one of: ${photos_1.SIZES.join(', ')}.`);
+    }
+    return size;
+}
+function version() {
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '..', 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+if (require.main === module) {
+    main().catch((error) => {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    });
+}

package/dist/photos.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIZES = void 0;
+exports.withUtm = withUtm;
+exports.compactPhoto = compactPhoto;
+exports.parsePhotoId = parsePhotoId;
+exports.downloadPhoto = downloadPhoto;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.SIZES = ['raw', 'full', 'regular', 'small', 'thumb'];
+function withUtm(url) {
+    if (!url)
+        return '';
+    const separator = url.includes('?') ? '&' : '?';
+    return `${url}${separator}utm_source=unsplash-cli&utm_medium=referral`;
+}
+function compactPhoto(photo, query = '') {
+    const user = photo.user ?? {};
+    const profile = user.links?.html || (user.username ? `https://unsplash.com/@${user.username}` : '');
+    const name = user.name || user.username || 'Unknown';
+    return {
+        id: photo.id,
+        description: photo.description || photo.alt_description || '',
+        width: photo.width,
+        height: photo.height,
+        color: photo.color || '',
+        urls: photo.urls,
+        photographer: {
+            name,
+            username: user.username || '',
+            profile_url: withUtm(profile),
+        },
+        photo_page: withUtm(photo.links?.html || ''),
+        download_location: photo.links?.download_location || '',
+        attribution: `Photo by ${name} on Unsplash (${withUtm(profile)})`,
+        ...(query ? { query } : {}),
+    };
+}
+function parsePhotoId(ref) {
+    if (/^[A-Za-z0-9_-]{6,}$/.test(ref))
+        return ref;
+    let parsed;
+    try {
+        parsed = new URL(ref);
+    }
+    catch {
+        throw new Error(`Invalid photo id or URL: ${ref}`);
+    }
+    const parts = parsed.pathname.split('/').filter(Boolean);
+    let last = parts.pop() ?? '';
+    if (last === 'download')
+        last = parts.pop() ?? '';
+    const id = last.includes('-') ? last.slice(last.lastIndexOf('-') + 1) : last;
+    if (!id)
+        throw new Error(`Could not parse photo id from URL: ${ref}`);
+    return id;
+}
+async function downloadPhoto(api, ref, options) {
+    const id = parsePhotoId(ref);
+    const photo = await api.photo(id);
+    const meta = compactPhoto(photo);
+    const source = photo.urls[options.size] ?? photo.urls.full ?? photo.urls.regular;
+    if (!source)
+        throw new Error(`Photo ${id} has no image URL for size ${options.size}.`);
+    const image = await api.fetchImage(source);
+    const extension = extensionFor(image.contentType);
+    const file = options.out ?? (0, node_path_1.join)(options.outDir ?? '.', `${id}${extension}`);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(file), { recursive: true });
+    (0, node_fs_1.writeFileSync)(file, image.buffer);
+    const shouldTrack = options.track !== false && Boolean(meta.download_location);
+    const tracked = shouldTrack ? await api.track(meta.download_location) : false;
+    if (shouldTrack && !tracked) {
+        console.error('warning: Unsplash download tracking failed; the image was saved.');
+    }
+    const record = {
+        provider: 'unsplash',
+        ...meta,
+        size: options.size,
+        file,
+        bytes: image.buffer.length,
+        download_tracked: tracked,
+        downloaded_at: new Date().toISOString(),
+        license: 'https://unsplash.com/license',
+        sidecar: null,
+    };
+    if (options.sidecar !== false) {
+        const sidecar = (0, node_path_1.join)((0, node_path_1.dirname)(file), `${(0, node_path_1.basename)(file, (0, node_path_1.extname)(file))}.json`);
+        (0, node_fs_1.writeFileSync)(sidecar, `${JSON.stringify(record, null, 2)}\n`);
+        record.sidecar = sidecar;
+    }
+    return record;
+}
+function extensionFor(contentType) {
+    if (contentType.includes('png'))
+        return '.png';
+    if (contentType.includes('webp'))
+        return '.webp';
+    if (contentType.includes('gif'))
+        return '.gif';
+    return '.jpg';
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@orangemust/unsplash-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Search and download Unsplash photos from the command line. API key stored in macOS Keychain, never in .env.",
+  "keywords": [
+    "unsplash",
+    "photos",
+    "images",
+    "stock-photos",
+    "cli",
+    "agent",
+    "automation"
+  ],
+  "license": "MIT",
+  "author": "mack-peng",
+  "main": "dist/index.js",
+  "bin": {
+    "unsplash": "bin/unsplash.js",
+    "unsplash-cli": "bin/unsplash.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "LICENSE",
+    "AGENTS.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/*.test.ts",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}