ima2-gen 1.0.1 → 1.0.3

package/README.md

@@ -1,82 +1,253 @@
 # ima2-gen
 
 [![npm version](https://img.shields.io/npm/v/ima2-gen)](https://www.npmjs.com/package/ima2-gen)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Minimal CLI + web UI for OpenAI `gpt-image-2` image generation.
+> **Read in other languages**: [한국어](docs/README.ko.md) · [日本語](docs/README.ja.md) · [简体中文](docs/README.zh-CN.md)
+
+Minimal CLI + web UI for OpenAI **GPT Image 2** (`gpt-image-2`) image generation. OAuth (free via ChatGPT Plus/Pro) or API key. Parallel generation, multi-image references, CLI automation, persistent history.
 
 ![ima2-gen screenshot](assets/screenshot.png)
 
-## Install & Run
+---
+
+## Quick Start
 
 ```bash
+# Run instantly with npx (no install)
 npx ima2-gen serve
-```
-
-Or install globally:
 
-```bash
+# Or install globally
 npm install -g ima2-gen
 ima2 serve
 ```
 
-First run prompts you to choose:
+First run prompts you to pick an auth method:
 
 ```
-  1) API Key  — paste your OpenAI API key (paid)
-  2) OAuth    — login with ChatGPT account (free)
+  Choose authentication method:
+    1) API Key  — paste your OpenAI API key (paid)
+    2) OAuth    — login with ChatGPT account (free)
 ```
 
-Then opens `http://localhost:3333`.
+Web UI opens at `http://localhost:3333`.
+
+---
+
+## Features
+
+Everything in the screenshot above, shipping today:
+
+### Authentication
+- **OAuth** — log in with your ChatGPT Plus/Pro account, $0 per image
+- **API Key** — paste your `sk-...` key, pay per call
+
+Both indicators shown live in the left panel (green dot = ready, red dot = disabled). API key path is hard-disabled by default; OAuth is the primary route.
+
+### Generation controls
+| Control | Options |
+|---------|---------|
+| **Quality** | Low (fast) · Medium (balanced) · High (best) |
+| **Size** | `1024²` `1536×1024` `1024×1536` `1360×1024` `1024×1360` `1824×1024` `1024×1824` `2048²` `2048×1152` `1152×2048` `3824×2160` `2160×3824` · `auto` · custom |
+| **Format** | PNG · JPEG · WebP |
+| **Moderation** | Low (less restrictive) · Auto (standard) |
+| **Count** | 1 · 2 · 4 parallel |
+
+All sizes respect gpt-image-2 constraints: every side is a multiple of 16, long:short ratio ≤ 3:1, 655,360–8,294,400 total pixels.
 
-## CLI
+### Workflow
+- **Multi-reference** — attach up to 5 reference images, drag & drop anywhere on the left panel
+- **Prompt-with-context** — mixes text + reference images in one request
+- **Use current** — one-click re-use of the selected image as a new reference
+- **Download** · **Copy to clipboard** · **Copy prompt** directly from the canvas
+- **Sticky gallery strip** at the bottom, fixed-position so it never scrolls away
+- **Gallery modal (+)** — grid view of everything in history
+- **Session persistence** — refresh mid-generation and your pending jobs reconcile automatically
 
+### CLI (headless automation)
 ```bash
-ima2 serve    # start server (auto-setup on first run)
-ima2 setup    # reconfigure auth
-ima2 reset    # clear saved config
+ima2 gen "a shiba in space" -q high -o shiba.png
+ima2 gen "merge these" --ref a.png --ref b.png -n 4 -d out/
+ima2 ls -n 10
+ima2 ps
+ima2 ping
 ```
 
-## Features
+Full command matrix below ↓
+
+---
+
+## CLI Commands
+
+### Server commands
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `ima2 serve` | — | Start the web server (auto-setup on first run) |
+| `ima2 setup` | `login` | Reconfigure authentication method |
+| `ima2 status` | — | Show current config & auth status |
+| `ima2 doctor` | — | Diagnose environment & dependencies |
+| `ima2 open` | — | Open web UI in browser |
+| `ima2 reset` | — | Clear saved configuration |
+| `ima2 --version` | `-v` | Show version |
+| `ima2 --help` | `-h` | Show help |
+
+### Client commands (require a running `ima2 serve`)
+| Command | Description |
+|---------|-------------|
+| `ima2 gen <prompt>` | Generate image(s) from the CLI |
+| `ima2 edit <file>` | Edit an existing image (requires `--prompt`) |
+| `ima2 ls` | List recent history (table or `--json`) |
+| `ima2 show <name>` | Reveal one history item (`--reveal`) |
+| `ima2 ps` | List active jobs (`--kind`, `--session`) |
+| `ima2 ping` | Health-check the running server |
+
+The running server advertises itself at `~/.ima2/server.json`. Client commands auto-discover it; override with `--server <url>` or `IMA2_SERVER=...`.
+
+### Exit codes
+`0` ok · `2` bad args · `3` server unreachable · `4` APIKEY_DISABLED · `5` 4xx · `6` 5xx · `7` safety refusal · `8` timeout.
+
+---
+
+## Roadmap
+
+Public roadmap — subject to change. Version numbers reflect the actual ship cycle, not time estimates.
+
+### ✅ Shipped
+- **0.06** Session DB — SQLite-backed history with sidecar JSON
+- **0.07** Multi-reference — up to 5 attachments, i2i merged into unified flow
+- **0.08** Inflight tracking — refresh-safe pending state, phase tracking
+- **0.09** Node mode (dev-only) — graph-based canvas for branching generations
+- **0.09.1** CLI integration — `gen / edit / ls / show / ps / ping` + `/api/health` + port advertisement
+
+### 🚧 0.10 — Compare & Reuse (current cycle)
+- **F3 Prompt presets** — save/apply `{prompt, refs, quality, size}` bundles
+- **F3 Gallery groupBy** — `preset / date / compareRun` grouping
+- **F2 Batch A/B compare** — spawn 2–6 parallel variants from one prompt, keyboard-driven judging (`1-6`, `Space`=winner, `V`=variation, `P`=save preset)
+- **F4 Export bundle** — zip selected images with `manifest.json` + per-image prompt `.txt`
+- Every server verb ships with its CLI mirror (`ima2 preset / compare / export`)
+
+### 🔭 0.11 — Card-news mode
+- Instagram carousel generation (4 / 6 / 10 cards)
+- Style consistency via `file_id` fan-out (not `previous_response_id`, not seed)
+- Parallel card regeneration without breaking the style chain
 
-- **Dual provider** — OAuth (free, ChatGPT account) or API Key (paid)
-- **Text-to-Image** — generate images from text prompts
-- **Image-to-Image** — edit/inpaint with drag-and-drop
-- **Quality** — low / medium / high
-- **Size** — presets (1024 ~ 4K) + custom (any 16px-aligned ratio)
-- **Format** — PNG / JPEG / WebP
-- **Moderation** — auto (standard) / low (less restrictive)
-- **Prompt display** — shown under image, click to copy
-- **History** — persisted across page refreshes (localStorage)
-- **Download / Copy** — save or clipboard
+### 🔭 0.12 — Style kit
+- Codified house-style presets with style-reference uploads
+- Optional `input_fidelity: "high"` for identity-critical edits
+
+### 🗂 Backlog
+- Web UI dark/light toggle
+- Keyboard shortcuts cheat-sheet overlay
+- Collaborative sessions (shared SQLite over WebSocket)
+- Plugin system for custom post-processing
+
+---
 
 ## Architecture
 
 ```
 ima2 serve
-  ├── Express (:3333)          ← web UI + API
-  └── openai-oauth (:10531)    ← embedded OAuth proxy
+  ├── Express server (:3333)
+  │   ├── GET  /api/health         — version, uptime, activeJobs, pid
+  │   ├── GET  /api/providers      — available auth methods
+  │   ├── GET  /api/oauth/status   — OAuth proxy health check
+  │   ├── POST /api/generate       — text+ref → image (parallel via n)
+  │   ├── POST /api/edit           — ref-heavy edit path
+  │   ├── GET  /api/history        — paginated sidecar listing
+  │   ├── GET  /api/inflight       — in-progress jobs (kind/session filters)
+  │   ├── GET  /api/sessions/*     — node-graph sessions (dev-only)
+  │   ├── GET  /api/billing        — API credit / cost info
+  │   └── Static files (public/)   — web UI
+  │
+  ├── openai-oauth proxy (:10531)  — embedded OAuth relay
+  └── ~/.ima2/server.json          — port advertisement for CLI auto-discovery
 ```
 
-## Config
+**Node mode** is dev-only (`npm run dev`) and gated from npm publishes until the session DB + multi-user story lands.
+
+---
+
+## Configuration
 
-Stored in `.ima2/config.json` (auto-created, gitignored).
+Config lives in `.ima2/config.json` (auto-created, gitignored).
 
-Optional `.env`:
+### Environment Variables
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENAI_API_KEY` | — | OpenAI API key (skips OAuth) |
+| `PORT` | `3333` | Web server port |
+| `OAUTH_PORT` | `10531` | OAuth proxy port |
+| `IMA2_SERVER` | — | Client: override target server URL |
+
+```bash
+cp .env.example .env
 ```
-OPENAI_API_KEY=sk-proj-...
-PORT=3333
-OAUTH_PORT=10531
+
+---
+
+## API Pricing (API Key mode only)
+
+| Quality | 1024×1024 | 1024×1536 | 1536×1024 | 2048×2048 | 3840×2160 |
+|---------|-----------|-----------|-----------|-----------|-----------|
+| Low     | $0.006    | $0.005    | $0.005    | $0.012    | $0.023    |
+| Medium  | $0.053    | $0.041    | $0.041    | $0.106    | $0.200    |
+| High    | $0.211    | $0.165    | $0.165    | $0.422    | $0.800    |
+
+**OAuth mode is free** — billed against your existing ChatGPT Plus/Pro plan.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/lidge-jun/ima2-gen.git
+cd ima2-gen
+npm install
+npm run dev    # server with --watch + Node mode enabled
+npm test       # 51+ tests (health, CLI lib, commands, server)
 ```
 
-## Pricing (API Key mode)
+Frontend stack:
+- Vanilla HTML/CSS/JS (no framework in the published build)
+- Vite + React for the Node-mode canvas (dev-only, gated)
+- Fonts: Outfit + Geist Mono
+
+## Tech Stack
+- **Runtime**: Node.js ≥18
+- **Server**: Express 5, SQLite (better-sqlite3)
+- **API**: OpenAI SDK v5
+- **OAuth**: `openai-oauth` proxy
+- **Tests**: Node built-in test runner
+
+---
+
+## Troubleshooting
+
+**Port already in use / "why is it on 3457?"**
+→ The default is `3333`. If `PORT` is set in your shell (e.g. inherited from another server like `cli-jaw`), ima2 uses that instead. Unset it or run `PORT=3333 ima2 serve`.
+
+**`ima2 ping` says server unreachable**
+→ Is `ima2 serve` running? Check `~/.ima2/server.json`. Override with `ima2 ping --server http://localhost:3333`.
 
-| Quality | 1024x1024 | 1024x1536 | 1536x1024 |
-|---------|-----------|-----------|-----------|
-| Low     | $0.006    | $0.005    | $0.005    |
-| Medium  | $0.053    | $0.041    | $0.041    |
-| High    | $0.211    | $0.165    | $0.165    |
+**OAuth login not working**
+→ Run `npx @openai/codex login` manually, then `ima2 serve`.
 
-OAuth mode is free (uses your ChatGPT Plus/Pro subscription).
+**`ima2 doctor` fails on node_modules**
+→ `npm install`.
+
+**Images not generating**
+→ `ima2 status` to verify config. API key must start with `sk-`.
+
+---
+
+## Release
+
+```bash
+npm run release:patch   # 1.0.2 → 1.0.3
+npm run release:minor   # 1.0.x → 1.1.0
+npm run release:major   # 1.x.x → 2.0.0
+```
 
 ## License
 

package/bin/commands/edit.js

@@ -0,0 +1,70 @@
+import { parseArgs } from "../lib/args.js";
+import { resolveServer, request } from "../lib/client.js";
+import { fileToDataUri, dataUriToFile, defaultOutName } from "../lib/files.js";
+import { out, die, color, json, exitCodeForError } from "../lib/output.js";
+
+const SPEC = {
+  flags: {
+    prompt:  { short: "p", type: "string" },
+    quality: { short: "q", type: "string", default: "low" },
+    size:    { short: "s", type: "string", default: "1024x1024" },
+    out:     { short: "o", type: "string" },
+    json:    {              type: "boolean" },
+    timeout: {              type: "string", default: "180" },
+    server:  {              type: "string" },
+    help:    { short: "h", type: "boolean" },
+  },
+};
+
+const HELP = `
+  ima2 edit <file> --prompt "<text>" [options]
+
+  Edit an existing image (inpainting-style).
+
+  Options:
+    -p, --prompt <text>        Edit instruction (required)
+    -q, --quality <low|medium|high|auto>
+    -s, --size <WxH>
+    -o, --out <file>
+        --json
+`;
+
+export default async function editCmd(argv) {
+  const args = parseArgs(argv, SPEC);
+  if (args.help) { out(HELP); return; }
+  const input = args.positional[0];
+  if (!input) die(2, "input image path required");
+  if (!args.prompt) die(2, "--prompt is required");
+
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); }
+  catch (e) { die(exitCodeForError(e), e.message); }
+
+  const imageDataUri = await fileToDataUri(input);
+  const imageB64 = imageDataUri.split(",")[1];
+
+  const timeoutMs = (parseInt(args.timeout) || 180) * 1000;
+  let resp;
+  try {
+    resp = await request(server.base, "/api/edit", {
+      method: "POST",
+      body: { prompt: args.prompt, image: imageB64, quality: args.quality, size: args.size },
+      timeoutMs,
+    });
+  } catch (e) {
+    if (args.json) json({ ok: false, error: e.message, code: e.code });
+    die(exitCodeForError(e), e.message);
+  }
+
+  const image = resp.image;
+  if (!image) die(1, "server returned no image");
+  const target = args.out || defaultOutName(0, 1);
+  await dataUriToFile(image, target);
+
+  if (args.json) {
+    json({ ok: true, path: target, requestId: resp.requestId, elapsed: resp.elapsed });
+  } else {
+    out(color.green("✓ ") + target);
+    if (resp.elapsed) out(color.dim(`elapsed ${resp.elapsed}s`));
+  }
+}

package/bin/commands/gen.js

@@ -0,0 +1,136 @@
+import { parseArgs } from "../lib/args.js";
+import { resolveServer, request, normalizeGenerate } from "../lib/client.js";
+import { fileToDataUri, dataUriToFile, defaultOutName, readStdin } from "../lib/files.js";
+import { out, err, die, color, json, exitCodeForError } from "../lib/output.js";
+
+const SPEC = {
+  flags: {
+    quality:   { short: "q", type: "string", default: "low" },
+    size:      { short: "s", type: "string", default: "1024x1024" },
+    count:     { short: "n", type: "string", default: "1" },
+    ref:       {              type: "string", repeatable: true },
+    out:       { short: "o", type: "string" },
+    "out-dir": { short: "d", type: "string" },
+    json:      {              type: "boolean" },
+    "no-save": {              type: "boolean" },
+    force:     {              type: "boolean" },
+    stdin:     {              type: "boolean" },
+    timeout:   {              type: "string", default: "180" },
+    server:    {              type: "string" },
+    help:      { short: "h", type: "boolean" },
+  },
+};
+
+const HELP = `
+  ima2 gen <prompt...> [options]
+
+  Generate image(s) via the running ima2 server.
+
+  Options:
+    -q, --quality <low|medium|high|auto>    Default: low
+    -s, --size <WxH | auto>                 Default: 1024x1024
+    -n, --count <1..8>                      Default: 1
+        --ref <file>                        Attach reference image (repeatable, max 5)
+    -o, --out <file>                        Single-image output path (implies -n 1)
+    -d, --out-dir <dir>                     Output dir for multiple images
+        --json                              Print JSON result to stdout
+        --no-save                           Skip save; print b64 to stdout (use --force for TTY)
+        --stdin                              Read prompt from stdin
+        --timeout <sec>                     Default: 180
+        --server <url>                      Override server URL
+
+  Examples:
+    ima2 gen "a shiba in space"
+    ima2 gen "merge" --ref a.png --ref b.png -q high -o out.png
+    cat prompt.txt | ima2 gen --stdin -n 2 -d ./out
+`;
+
+export default async function genCmd(argv) {
+  const args = parseArgs(argv, SPEC);
+  if (args.help) { out(HELP); return; }
+
+  let prompt = args.positional.join(" ");
+  if (args.stdin) {
+    const piped = await readStdin();
+    if (piped) prompt = prompt ? `${prompt} ${piped}` : piped;
+  }
+  if (!prompt) die(2, "prompt is required (positional or via --stdin)");
+
+  const refs = args.ref || [];
+  if (refs.length > 5) die(2, "max 5 --ref attachments");
+
+  const n = Math.max(1, Math.min(8, parseInt(args.count) || 1));
+  const timeoutMs = (parseInt(args.timeout) || 180) * 1000;
+
+  let server;
+  try {
+    server = await resolveServer({ serverFlag: args.server });
+  } catch (e) {
+    die(exitCodeForError(e), e.message);
+  }
+
+  const references = await Promise.all(refs.map((p) => fileToDataUri(p)));
+
+  const body = {
+    prompt,
+    quality: args.quality,
+    size: args.size,
+    n,
+    references,
+  };
+
+  let resp;
+  try {
+    resp = await request(server.base, "/api/generate", { method: "POST", body, timeoutMs });
+  } catch (e) {
+    if (args.json) json({ ok: false, error: e.message, code: e.code, status: e.status });
+    die(exitCodeForError(e), e.message);
+  }
+
+  const norm = normalizeGenerate(resp);
+  if (norm.images.length === 0) die(1, "server returned no images");
+
+  // --no-save path
+  if (args["no-save"]) {
+    const totalBytes = norm.images.reduce((s, im) => s + im.image.length, 0);
+    if (process.stdout.isTTY && totalBytes > 2 * 1024 * 1024 && !args.force) {
+      die(2, "refusing to print >2MB of b64 to TTY; use --force or drop --no-save");
+    }
+    for (const im of norm.images) out(im.image);
+    return;
+  }
+
+  // Save path
+  const outDir = args["out-dir"] || null;
+  const explicitOut = args.out || null;
+  if (explicitOut && norm.images.length > 1) {
+    die(2, "--out only supports a single image; use --out-dir for n>1");
+  }
+
+  const savedPaths = [];
+  for (let i = 0; i < norm.images.length; i++) {
+    const im = norm.images[i];
+    let target;
+    if (explicitOut) {
+      target = explicitOut;
+    } else if (outDir) {
+      target = `${outDir}/${defaultOutName(i, norm.images.length)}`;
+    } else {
+      target = defaultOutName(i, norm.images.length);
+    }
+    await dataUriToFile(im.image, target);
+    savedPaths.push(target);
+  }
+
+  if (args.json) {
+    json({
+      ok: true,
+      requestId: norm.requestId,
+      elapsed: norm.elapsed,
+      images: savedPaths.map((p, i) => ({ path: p, filename: norm.images[i].filename })),
+    });
+  } else {
+    for (const p of savedPaths) out(color.green("✓ ") + p);
+    if (norm.elapsed) out(color.dim(`elapsed ${norm.elapsed}s`));
+  }
+}

package/bin/commands/ls.js

@@ -0,0 +1,49 @@
+import { parseArgs } from "../lib/args.js";
+import { resolveServer, request } from "../lib/client.js";
+import { out, die, color, json, table, exitCodeForError } from "../lib/output.js";
+
+const SPEC = {
+  flags: {
+    count:  { short: "n", type: "string", default: "20" },
+    json:   { type: "boolean" },
+    server: { type: "string" },
+    help:   { short: "h", type: "boolean" },
+  },
+};
+
+export default async function lsCmd(argv) {
+  const args = parseArgs(argv, SPEC);
+  if (args.help) { out("ima2 ls [-n count] [--json]"); return; }
+
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); }
+  catch (e) { die(exitCodeForError(e), e.message); }
+
+  const limit = parseInt(args.count) || 20;
+  let resp;
+  try { resp = await request(server.base, "/api/history"); }
+  catch (e) { die(exitCodeForError(e), e.message); }
+
+  const items = (resp.items || resp.history || []).slice(0, limit);
+
+  if (args.json) { json({ items }); return; }
+
+  if (items.length === 0) {
+    out(color.dim("(no history)"));
+    return;
+  }
+  table(items, [
+    { key: "filename", label: "FILENAME" },
+    { key: "quality",  label: "Q" },
+    { key: "size",     label: "SIZE" },
+    { key: "createdAt", label: "WHEN", format: (v) => {
+      if (!v) return "";
+      const d = new Date(v);
+      return d.toISOString().replace("T", " ").slice(0, 19);
+    } },
+    { key: "prompt", label: "PROMPT", format: (v) => {
+      const s = String(v || "").replace(/\s+/g, " ");
+      return s.length > 48 ? s.slice(0, 45) + "…" : s;
+    } },
+  ]);
+}

package/bin/commands/ping.js

@@ -0,0 +1,28 @@
+import { parseArgs } from "../lib/args.js";
+import { resolveServer } from "../lib/client.js";
+import { out, die, color, json, exitCodeForError } from "../lib/output.js";
+
+const SPEC = {
+  flags: {
+    json:   { type: "boolean" },
+    server: { type: "string" },
+    help:   { short: "h", type: "boolean" },
+  },
+};
+
+export default async function pingCmd(argv) {
+  const args = parseArgs(argv, SPEC);
+  if (args.help) { out("ima2 ping [--json]"); return; }
+
+  try {
+    const { base, health } = await resolveServer({ serverFlag: args.server });
+    if (args.json) {
+      json({ ok: true, base, ...health });
+    } else {
+      out(color.green("✓ ") + `${base}  v${health.version}  uptime ${health.uptimeSec}s  activeJobs ${health.activeJobs}`);
+    }
+  } catch (e) {
+    if (args.json) { json({ ok: false, error: e.message }); process.exit(exitCodeForError(e)); }
+    die(exitCodeForError(e), e.message);
+  }
+}

package/bin/commands/ps.js

@@ -0,0 +1,46 @@
+import { parseArgs } from "../lib/args.js";
+import { resolveServer, request } from "../lib/client.js";
+import { out, die, color, json, table, exitCodeForError } from "../lib/output.js";
+
+const SPEC = {
+  flags: {
+    kind:    { type: "string" },
+    session: { type: "string" },
+    json:    { type: "boolean" },
+    server:  { type: "string" },
+    help:    { short: "h", type: "boolean" },
+  },
+};
+
+export default async function psCmd(argv) {
+  const args = parseArgs(argv, SPEC);
+  if (args.help) { out("ima2 ps [--kind classic|node] [--session id] [--json]"); return; }
+
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); }
+  catch (e) { die(exitCodeForError(e), e.message); }
+
+  const qs = new URLSearchParams();
+  if (args.kind) qs.set("kind", args.kind);
+  if (args.session) qs.set("sessionId", args.session);
+  const path = `/api/inflight${qs.toString() ? `?${qs}` : ""}`;
+  let resp;
+  try { resp = await request(server.base, path); }
+  catch (e) { die(exitCodeForError(e), e.message); }
+
+  const jobs = resp.jobs || resp.items || [];
+  if (args.json) { json({ jobs }); return; }
+  if (jobs.length === 0) { out(color.dim("(no active jobs)")); return; }
+
+  const now = Date.now();
+  table(jobs, [
+    { key: "requestId", label: "ID", format: (v) => String(v || "").slice(0, 10) },
+    { key: "kind", label: "KIND" },
+    { key: "phase", label: "PHASE" },
+    { key: "startedAt", label: "AGE", format: (v) => v ? `${Math.round((now - v) / 1000)}s` : "" },
+    { key: "prompt", label: "PROMPT", format: (v) => {
+      const s = String(v || "").replace(/\s+/g, " ");
+      return s.length > 40 ? s.slice(0, 37) + "…" : s;
+    } },
+  ]);
+}

package/bin/commands/show.js

@@ -0,0 +1,57 @@
+import { parseArgs } from "../lib/args.js";
+import { resolveServer, request } from "../lib/client.js";
+import { execSync } from "node:child_process";
+import { out, die, color, json, exitCodeForError } from "../lib/output.js";
+import { join } from "node:path";
+
+const SPEC = {
+  flags: {
+    json:   { type: "boolean" },
+    reveal: { type: "boolean" },
+    server: { type: "string" },
+    help:   { short: "h", type: "boolean" },
+  },
+};
+
+export default async function showCmd(argv) {
+  const args = parseArgs(argv, SPEC);
+  if (args.help) { out("ima2 show <filename> [--json] [--reveal]"); return; }
+  const name = args.positional[0];
+  if (!name) die(2, "filename required");
+
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); }
+  catch (e) { die(exitCodeForError(e), e.message); }
+
+  let resp;
+  try { resp = await request(server.base, "/api/history"); }
+  catch (e) { die(exitCodeForError(e), e.message); }
+
+  const items = resp.items || resp.history || [];
+  const item = items.find((it) => it.filename === name || (it.filename && it.filename.endsWith(name)));
+  if (!item) die(1, `not found: ${name}`);
+
+  if (args.json) { json(item); }
+  else {
+    out(color.bold(item.filename));
+    out(color.dim(`  prompt:`)   + ` ${item.prompt || ""}`);
+    out(color.dim(`  size:`)     + ` ${item.size || ""}  quality: ${item.quality || ""}`);
+    if (item.createdAt) out(color.dim(`  when:`) + ` ${new Date(item.createdAt).toISOString()}`);
+    if (item.url) out(color.dim(`  url:`) + ` ${server.base}${item.url}`);
+  }
+
+  if (args.reveal) {
+    const url = item.url ? `${server.base}${item.url}` : null;
+    try {
+      if (process.platform === "darwin") {
+        execSync(`open "${server.base}${item.url || ""}"`);
+      } else if (process.platform === "win32") {
+        execSync(`start "" "${url}"`);
+      } else {
+        execSync(`xdg-open "${url}"`);
+      }
+    } catch {
+      out(color.yellow("(could not reveal)"));
+    }
+  }
+}