ima2-gen 1.0.10 → 1.1.0

package/docs/README.zh-CN.md

@@ -0,0 +1,182 @@
+# 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%3D20-brightgreen)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE)
+
+> **其他语言**: [English](../README.md) · [한국어](README.ko.md) · [日本語](README.ja.md)
+
+`ima2-gen` 是一个本地图像生成工作室，让你像使用小型桌面应用一样使用 ChatGPT/Codex OAuth 图像生成流程。
+
+用 `npx` 启动，登录 Codex OAuth，输入 prompt，然后通过历史记录、参考图、style sheet 和节点分支持续迭代。默认图像生成路径不需要 OpenAI API key。
+
+![显示 prompt 输入区、生成图片、模型标签和结果元数据的 ima2-gen classic 界面](../assets/screenshots/classic-generate-light.png)
+
+## 快速开始
+
+```bash
+npx ima2-gen serve
+```
+
+然后打开 `http://localhost:3333`。
+
+如果还没有登录 Codex：
+
+```bash
+npx @openai/codex login
+npx ima2-gen serve
+```
+
+也可以全局安装：
+
+```bash
+npm install -g ima2-gen
+ima2 serve
+```
+
+## 能做什么
+
+- **Classic mode**：快速生成、编辑，并把当前图片继续作为参考图使用。
+- **Node mode**：从一张满意的图出发，向多个方向分支探索。
+- **Local gallery**：把生成结果保存在本机，并按 session 查看历史。
+- **Reference images**：支持拖放、粘贴和文件选择；大图会在上传前自动压缩。
+- **Style sheets**：保存一套视觉方向，并复用到 classic/node prompt。
+- **Observable jobs**：用 request ID 追踪进行中和最近完成的任务。
+
+## 图像生成只走 OAuth
+
+当前图像生成通过本地 Codex/ChatGPT OAuth 路径执行。
+
+即使 env/config 里有 API key，它也只可能用于 billing 检查或 style-sheet 提取等辅助功能。生成接口收到 `provider: "api"` 时会返回 `APIKEY_DISABLED`。
+
+如果设置页显示 **Configured but disabled**，意思是检测到了 API key，但图像生成仍然使用 OAuth。
+
+![显示 OAuth active 与 API key disabled 状态的设置页](../assets/screenshots/settings-oauth-generation.png)
+
+## 模型建议
+
+如果想要稳定、均衡的结果，建议先从 **`gpt-5.4`** 开始。
+
+- `gpt-5.4` — 推荐的均衡选择。
+- `gpt-5.4-mini` — 当前应用默认值，适合快速草稿。
+- `gpt-5.5` — 在支持的环境中是质量最强的选择。但它可能消耗更多额度，也可能需要更新 Codex CLI，或依赖账号/后端路径是否开放对应的图像 capability。
+
+Quality 支持 `low`, `medium`, `high`；moderation 支持 `auto`, `low`。
+
+## 工作流
+
+### Classic mode
+
+适合快速做出一张图并继续调整。
+
+1. 写 prompt。
+2. 需要时添加参考图。
+3. 选择模型、quality、size、format、moderation。
+4. 生成后复制、下载，或继续从当前结果迭代。
+
+### Node mode
+
+适合把想法分叉后对比。
+
+![显示连接节点、生成卡片和节点元数据的 Node mode 界面](../assets/screenshots/node-graph-branching.png)
+
+每个节点都有自己的 prompt 和结果。根节点可以附加本地参考图；子节点会使用父图作为来源。完成的任务会通过 request ID 重新匹配，因此刷新或 graph version conflict 后也能恢复结果。
+
+### Settings 和 Style sheets
+
+Settings workspace 会把账号、模型、主题和语言设置从生成面板中分离出来。
+
+![显示账号区域和生成模型设置的 Settings workspace](../assets/screenshots/settings-workspace.png)
+
+Style sheet 用来保存可复用的视觉方向。
+
+![包含 medium、composition、mood、subject、palette、negative 字段的 style sheet editor](../assets/screenshots/style-sheet-editor.png)
+
+## CLI 命令
+
+### Server
+
+| Command | Description |
+|---|---|
+| `ima2 serve` | 启动本地 Web server |
+| `ima2 setup` | 重新配置认证 |
+| `ima2 status` | 查看 config 和 OAuth 状态 |
+| `ima2 doctor` | 诊断 Node、package、config、auth |
+| `ima2 open` | 打开 Web UI |
+| `ima2 reset` | 删除已保存的 config |
+
+### Client
+
+这些命令需要先运行 `ima2 serve`。
+
+| Command | Description |
+|---|---|
+| `ima2 gen <prompt>` | 从 CLI 生成图片 |
+| `ima2 edit <file> --prompt <text>` | 编辑已有图片 |
+| `ima2 ls` | 查看本地历史 |
+| `ima2 show <name>` | 打开生成文件 |
+| `ima2 ps` | 查看进行中的任务 |
+| `ima2 ping` | 检查 server 是否可用 |
+
+Server 端口会写入 `~/.ima2/server.json`。也可以用 `--server <url>` 或 `IMA2_SERVER=http://localhost:3333` 覆盖。
+
+## 配置
+
+优先级：
+
+```text
+environment variables > ~/.ima2/config.json > built-in defaults
+```
+
+| Variable | Default | Description |
+|---|---:|---|
+| `IMA2_PORT` / `PORT` | `3333` | Web server port |
+| `IMA2_OAUTH_PROXY_PORT` / `OAUTH_PORT` | `10531` | OAuth proxy port |
+| `IMA2_SERVER` | — | CLI target override |
+| `IMA2_CONFIG_DIR` | `~/.ima2` | Config 和 SQLite 位置 |
+| `IMA2_GENERATED_DIR` | `~/.ima2/generated` | 生成图片目录 |
+| `IMA2_NO_OAUTH_PROXY` | — | 设为 `1` 时关闭 OAuth proxy 自动启动 |
+| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | 调试用 recent job 保留时间 |
+| `OPENAI_API_KEY` | — | 辅助功能用 API key，不用于图像生成 |
+
+## API 文档
+
+接口列表已移到 [API Reference](API.md)。
+
+## 常见问题
+
+**`ima2 ping` 提示 server unreachable**
+先启动 `ima2 serve`，再检查 `~/.ima2/server.json`。也可以运行 `ima2 ping --server http://localhost:3333`。
+
+**OAuth 登录失败**
+运行 `npx @openai/codex login`，用 `ima2 status` 确认状态，然后重启 `ima2 serve`。
+
+**生成图片时返回 `APIKEY_DISABLED`**
+当前 build 需要使用 OAuth 生成。API-key image generation 是有意关闭的。
+
+**大参考图上传失败**
+JPEG/PNG 会在上传前自动压缩。如果仍然失败，请转成更低分辨率的 JPEG/PNG。HEIC/HEIF 不支持浏览器路径。
+
+**更新后看不到旧图库图片**
+新版本把生成图片目录从已安装的 package 文件夹移到了 `~/.ima2/generated`。请运行 `ima2 doctor`，并查看[旧图片恢复指南](RECOVER_OLD_IMAGES.md)。
+
+**只有 `gpt-5.5` 失败**
+请先更新 Codex CLI 后再试。如果仍然失败，说明当前账号或后端路径下 `gpt-5.5` 的图像 capability 或额度策略可能还不同；稳定替代方案是使用 `gpt-5.4`。
+
+**端口突然变成 `3457`**
+shell 可能继承了其他本地工具的 `PORT=3457`。运行 `unset PORT`，或使用 `IMA2_PORT=3333 ima2 serve`。
+
+## Development
+
+```bash
+git clone https://github.com/lidge-jun/ima2-gen.git
+cd ima2-gen
+npm install
+npm run dev
+npm test
+npm run build
+```
+
+## License
+
+MIT

package/docs/RECOVER_OLD_IMAGES.md

@@ -0,0 +1,91 @@
+# Recover Old Generated Images
+
+`ima2-gen` moved generated images to a safer user-data folder in `v1.0.8`.
+
+## What changed
+
+Versions up to `v1.0.7` stored generated images inside the installed package:
+
+```text
+<global node_modules>/ima2-gen/generated
+```
+
+Starting with `v1.0.8`, generated images are stored under your user data folder:
+
+```text
+macOS / Linux: ~/.ima2/generated
+Windows: %USERPROFILE%\.ima2\generated
+```
+
+This prevents future package updates from mixing application code and runtime user files.
+
+## Why images may look missing
+
+Sorry for the scare. Older global installs may have kept images inside the package folder. If that old global install folder was replaced during an update, the previous `generated/` folder may no longer be on disk.
+
+`ima2-gen` can copy old images only when the old folder still exists. If no old folder can be found, recovery may require a backup.
+
+## First check
+
+Run:
+
+```bash
+ima2 doctor
+```
+
+The Storage section shows the current gallery folder and whether legacy folders were found.
+
+## macOS / Linux: find old folders
+
+```bash
+find ~/.ima2 ~/.npm-global ~/.nvm ~/.fnm ~/.volta ~/.bun ~/.config/yarn ~/Library/pnpm ~/.local/share/pnpm ~/.asdf ~/.local/share/mise /usr/local /opt/homebrew \
+  -path '*ima2-gen/generated' -type d 2>/dev/null
+```
+
+If you used `npx` or `npm exec`:
+
+```bash
+find "$(npm config get cache)/_npx" \
+  -path '*/node_modules/ima2-gen/generated' -type d 2>/dev/null
+```
+
+## Windows PowerShell: find old folders
+
+```powershell
+$roots = @($env:USERPROFILE, $env:APPDATA, $env:LOCALAPPDATA, $env:NVM_HOME, "C:\Program Files\nodejs")
+foreach ($r in $roots) {
+  if (Test-Path $r) {
+    Get-ChildItem -Path $r -Recurse -Directory -ErrorAction SilentlyContinue |
+      Where-Object { $_.FullName -match 'ima2-gen[\\/]+generated$' } |
+      Select-Object -ExpandProperty FullName
+  }
+}
+```
+
+If you used `npx` or `npm exec`:
+
+```powershell
+Get-ChildItem "$env:LOCALAPPDATA\npm-cache\_npx" -Recurse -Directory -Filter generated -ErrorAction SilentlyContinue |
+  Where-Object { $_.FullName -match 'node_modules\\ima2-gen\\generated$' } |
+  Select-Object -ExpandProperty FullName
+```
+
+## Copy found files into the new location
+
+macOS / Linux:
+
+```bash
+mkdir -p ~/.ima2/generated
+cp -n "/path/to/old/ima2-gen/generated/"* ~/.ima2/generated/
+```
+
+Windows PowerShell:
+
+```powershell
+New-Item -ItemType Directory -Force "$env:USERPROFILE\.ima2\generated"
+Copy-Item "C:\path\to\old\ima2-gen\generated\*" "$env:USERPROFILE\.ima2\generated" -Recurse -Force:$false
+```
+
+## Important
+
+Do not delete old global install folders or npm caches until you confirm your images are visible in the app again.

package/lib/historyList.js

@@ -45,6 +45,7 @@ export async function listHistoryRows(baseDir = config.storage.generatedDir) {
       quality: meta?.quality || null,
       size: meta?.size || null,
       format: meta?.format || name.split(".").pop(),
+      model: meta?.model || null,
       provider: meta?.provider || "oauth",
       usage: meta?.usage || null,
       webSearchCalls: meta?.webSearchCalls || 0,

package/lib/imageModels.js

@@ -0,0 +1,32 @@
+const FALLBACK_IMAGE_MODEL = "gpt-5.4-mini";
+const VALID_IMAGE_MODELS = new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini"]);
+const UNSUPPORTED_IMAGE_MODELS = new Set(["gpt-5.3-codex-spark"]);
+
+export function normalizeImageModel(ctx, rawModel) {
+  const configured = ctx?.config?.imageModels;
+  const fallback = configured?.default ?? FALLBACK_IMAGE_MODEL;
+  const valid = configured?.valid ?? VALID_IMAGE_MODELS;
+  const unsupported = configured?.unsupported ?? UNSUPPORTED_IMAGE_MODELS;
+
+  if (typeof rawModel !== "string" || rawModel.length === 0) {
+    return { model: valid.has(fallback) ? fallback : FALLBACK_IMAGE_MODEL };
+  }
+
+  if (unsupported.has(rawModel)) {
+    return {
+      error: "model is listed by OAuth but does not support image_generation: gpt-5.3-codex-spark",
+      code: "IMAGE_MODEL_UNSUPPORTED",
+      status: 400,
+    };
+  }
+
+  if (!valid.has(rawModel)) {
+    return {
+      error: "model must be one of: gpt-5.5, gpt-5.4, gpt-5.4-mini",
+      code: "INVALID_IMAGE_MODEL",
+      status: 400,
+    };
+  }
+
+  return { model: rawModel };
+}

package/lib/oauthProxy.js

@@ -155,6 +155,7 @@ export async function generateViaOAuth(
   options = {},
 ) {
   const oauthUrl = getOAuthUrl(ctx);
+  const model = options.model || ctx.config?.imageModels?.default || "gpt-5.4-mini";
   const tools = [
     { type: "web_search" },
     {
@@ -181,7 +182,7 @@ export async function generateViaOAuth(
     method: "POST",
     headers: { "Content-Type": "application/json", Accept: "text/event-stream" },
     body: JSON.stringify({
-      model: "gpt-5.4",
+      model,
       input: [
         { role: "developer", content: GENERATE_DEVELOPER_PROMPT },
         { role: "user", content: userContent },
@@ -194,6 +195,7 @@ export async function generateViaOAuth(
 
   logEvent("oauth", "response", {
     requestId,
+    model,
     status: res.status,
     contentType: res.headers.get("content-type"),
   });
@@ -236,7 +238,7 @@ export async function generateViaOAuth(
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
-        model: "gpt-5.4",
+        model,
         input: [{ role: "user", content: buildUserTextPrompt(prompt, mode) }],
         tools: [{ type: "image_generation", quality, size, moderation }],
         stream: false,
@@ -260,15 +262,16 @@ export async function generateViaOAuth(
   return { b64: imageB64, usage, webSearchCalls, revisedPrompt };
 }
 
-export async function editViaOAuth(prompt, imageB64, quality, size, moderation = "low", mode = "auto", ctx = {}, requestId = null) {
+export async function editViaOAuth(prompt, imageB64, quality, size, moderation = "low", mode = "auto", ctx = {}, requestId = null, options = {}) {
   const oauthUrl = getOAuthUrl(ctx);
+  const model = options.model || ctx.config?.imageModels?.default || "gpt-5.4-mini";
   const textPrompt = buildEditTextPrompt(prompt, mode);
 
   const res = await fetch(`${oauthUrl}/v1/responses`, {
     method: "POST",
     headers: { "Content-Type": "application/json", Accept: "text/event-stream" },
     body: JSON.stringify({
-      model: "gpt-5.4",
+      model,
       input: [
         { role: "developer", content: EDIT_DEVELOPER_PROMPT },
         {
@@ -287,6 +290,7 @@ export async function editViaOAuth(prompt, imageB64, quality, size, moderation =
 
   logEvent("oauth-edit", "response", {
     requestId,
+    model,
     status: res.status,
     contentType: res.headers.get("content-type"),
   });

package/lib/openDirectory.js

@@ -0,0 +1,35 @@
+import { spawn } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+
+export async function openDirectory(dir, options = {}) {
+  await mkdir(dir, { recursive: true });
+  const platform = options.platform || process.platform;
+  const spawnImpl = options.spawnImpl || spawn;
+  const command =
+    platform === "darwin" ? "open"
+    : platform === "win32" ? "explorer"
+    : "xdg-open";
+
+  return new Promise((resolve) => {
+    try {
+      const child = spawnImpl(command, [dir], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      let settled = false;
+      const done = (result) => {
+        if (settled) return;
+        settled = true;
+        resolve(result);
+      };
+      child.on("error", (err) => {
+        done({ ok: false, error: err.message || String(err) });
+      });
+      child.unref?.();
+      setTimeout(() => done({ ok: true }), 50).unref?.();
+    } catch (err) {
+      resolve({ ok: false, error: err?.message || String(err) });
+    }
+  });
+}

package/lib/storageMigration.js

@@ -1,9 +1,9 @@
-import { mkdir, readdir, copyFile, stat } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { mkdir, readdir, copyFile, stat, constants } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 
 const PACKAGE_NAME = "ima2-gen";
+const RECOVERY_DOCS_PATH = "docs/RECOVER_OLD_IMAGES.md";
 
 function addStats(a, b) {
   return {
@@ -24,12 +24,13 @@ async function copyMissingTree(srcDir, dstDir) {
       continue;
     }
     if (!entry.isFile()) continue;
-    if (existsSync(dst)) {
+    try {
+      await copyFile(src, dst, constants.COPYFILE_EXCL);
+      stats.copied += 1;
+    } catch (err) {
+      if (err?.code !== "EEXIST") throw err;
       stats.skippedExisting += 1;
-      continue;
     }
-    await copyFile(src, dst);
-    stats.copied += 1;
   }
   return stats;
 }
@@ -42,7 +43,7 @@ function isSameOrInside(child, parent) {
 
 export async function migrateGeneratedStorage(ctx, options = {}) {
   const targetDir = ctx.config.storage.generatedDir;
-  const candidates = options.legacyDirs || getLegacyGeneratedCandidates(ctx, options.env);
+  const candidates = options.legacyDirs || await getLegacyGeneratedCandidates(ctx, options.env);
   const result = {
     copied: 0,
     skippedExisting: 0,
@@ -75,13 +76,18 @@ export async function migrateGeneratedStorage(ctx, options = {}) {
   return result;
 }
 
-export function getLegacyGeneratedCandidates(ctx, env = process.env) {
+export async function getLegacyGeneratedCandidates(ctx, env = process.env) {
   const home = env.IMA2_TEST_HOME || homedir();
   const execPath = env.IMA2_TEST_EXEC_PATH || process.execPath;
   const argv1 = env.IMA2_TEST_ARGV1 || process.argv[1] || "";
   const nodePrefix = dirname(dirname(execPath));
   const prefixes = getGlobalPrefixCandidates({ env, execPath, argv1 });
   const appData = env.APPDATA || join(home, "AppData", "Roaming");
+  const localAppData = env.LOCALAPPDATA || join(home, "AppData", "Local");
+  const npmCache = env.npm_config_cache || join(home, ".npm");
+  const xdgDataHome = env.XDG_DATA_HOME || join(home, ".local", "share");
+  const pnpmHome = env.PNPM_HOME || "";
+  const nvmHome = env.NVM_HOME || join(appData, "nvm");
 
   const candidates = [
     join(ctx.rootDir, "generated"),
@@ -90,6 +96,12 @@ export function getLegacyGeneratedCandidates(ctx, env = process.env) {
     join(home, ".nvm", "versions", "node", process.version, "lib", "node_modules", PACKAGE_NAME, "generated"),
     join(home, ".volta", "tools", "image", "packages", PACKAGE_NAME, "lib", "node_modules", PACKAGE_NAME, "generated"),
     join(home, ".fnm", "node-versions", process.version, "installation", "lib", "node_modules", PACKAGE_NAME, "generated"),
+    join(home, ".bun", "install", "global", "node_modules", PACKAGE_NAME, "generated"),
+    join(home, ".config", "yarn", "global", "node_modules", PACKAGE_NAME, "generated"),
+    join(localAppData, "Yarn", "Data", "global", "node_modules", PACKAGE_NAME, "generated"),
+    join(localAppData, "Volta", "tools", "image", "packages", PACKAGE_NAME, "lib", "node_modules", PACKAGE_NAME, "generated"),
+    join(nvmHome, process.version, "node_modules", PACKAGE_NAME, "generated"),
+    join(dirname(execPath), "node_modules", PACKAGE_NAME, "generated"),
   ];
 
   for (const prefix of prefixes) {
@@ -98,7 +110,160 @@ export function getLegacyGeneratedCandidates(ctx, env = process.env) {
   }
 
   candidates.push(join(nodePrefix, "lib", "node_modules", PACKAGE_NAME, "generated"));
-  return Array.from(new Set(candidates.map((p) => resolve(p))));
+  candidates.push(
+    ...await expandOneLevelCandidates([
+      [join(home, ".nvm", "versions", "node"), ["*", "lib", "node_modules", PACKAGE_NAME, "generated"]],
+      [join(home, ".fnm", "node-versions"), ["*", "installation", "lib", "node_modules", PACKAGE_NAME, "generated"]],
+      [join(home, ".asdf", "installs", "nodejs"), ["*", "lib", "node_modules", PACKAGE_NAME, "generated"]],
+      [join(home, ".local", "share", "mise", "installs", "node"), ["*", "lib", "node_modules", PACKAGE_NAME, "generated"]],
+      [join(home, "Library", "pnpm", "global"), ["*", "node_modules", PACKAGE_NAME, "generated"]],
+      [join(xdgDataHome, "pnpm", "global"), ["*", "node_modules", PACKAGE_NAME, "generated"]],
+      [join(localAppData, "pnpm", "global"), ["*", "node_modules", PACKAGE_NAME, "generated"]],
+      [pnpmHome ? join(pnpmHome, "global") : "", ["*", "node_modules", PACKAGE_NAME, "generated"]],
+      [join(npmCache, "_npx"), ["*", "node_modules", PACKAGE_NAME, "generated"]],
+      [join(localAppData, "npm-cache", "_npx"), ["*", "node_modules", PACKAGE_NAME, "generated"]],
+      [join(appData, "npm-cache", "_npx"), ["*", "node_modules", PACKAGE_NAME, "generated"]],
+      [nvmHome, ["*", "node_modules", PACKAGE_NAME, "generated"]],
+    ]),
+  );
+  return uniqueResolvedCandidates(candidates);
+}
+
+export async function inspectGeneratedStorage(ctx, options = {}) {
+  const env = options.env || process.env;
+  const targetDir = ctx.config.storage.generatedDir;
+  try {
+    const candidates = options.legacyDirs || await getLegacyGeneratedCandidates(ctx, env);
+    const targetFileCount = await countFiles(targetDir);
+    const legacySources = [];
+
+    for (const candidate of candidates) {
+      if (isSameOrInside(candidate, targetDir) || isSameOrInside(targetDir, candidate)) continue;
+      try {
+        const candidateStat = await stat(candidate);
+        if (!candidateStat.isDirectory()) continue;
+        const fileCount = await countFiles(candidate);
+        if (fileCount > 0) legacySources.push({ path: candidate, fileCount });
+      } catch (err) {
+        if (err?.code !== "ENOENT") {
+          console.warn("[storage] legacy candidate inspect skipped:", candidate, err.message);
+        }
+      }
+    }
+
+    const legacyFilesFound = legacySources.reduce((sum, source) => sum + source.fileCount, 0);
+    const state =
+      targetFileCount > 0 ? "ok"
+      : legacyFilesFound > 0 ? "recoverable"
+      : "not_found";
+
+    return {
+      ok: true,
+      targetDir,
+      generatedDirLabel: labelPath(targetDir, env),
+      targetExists: await isDirectory(targetDir),
+      targetFileCount,
+      legacyCandidatesScanned: candidates.length,
+      legacySourcesFound: legacySources.length,
+      legacyFilesFound,
+      legacySources,
+      overrides: {
+        generatedDir: Boolean(env.IMA2_GENERATED_DIR),
+        configDir: Boolean(env.IMA2_CONFIG_DIR),
+      },
+      state,
+      messageKind: state === "not_found" ? "apology" : state,
+      recoveryDocsPath: RECOVERY_DOCS_PATH,
+      doctorCommand: "ima2 doctor",
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      targetDir,
+      generatedDirLabel: labelPath(targetDir, env),
+      targetExists: false,
+      targetFileCount: 0,
+      legacyCandidatesScanned: 0,
+      legacySourcesFound: 0,
+      legacyFilesFound: 0,
+      legacySources: [],
+      overrides: {
+        generatedDir: Boolean(env.IMA2_GENERATED_DIR),
+        configDir: Boolean(env.IMA2_CONFIG_DIR),
+      },
+      state: "unknown",
+      messageKind: "unknown",
+      recoveryDocsPath: RECOVERY_DOCS_PATH,
+      doctorCommand: "ima2 doctor",
+      error: err?.message || String(err),
+    };
+  }
+}
+
+async function expandOneLevelCandidates(patterns) {
+  const candidates = [];
+  for (const [baseDir, segments] of patterns) {
+    if (!baseDir) continue;
+    candidates.push(...await expandOneLevelPattern(baseDir, segments));
+  }
+  return candidates;
+}
+
+async function expandOneLevelPattern(baseDir, segments) {
+  const wildcardIndex = segments.indexOf("*");
+  if (wildcardIndex < 0) return [join(baseDir, ...segments)];
+
+  const before = segments.slice(0, wildcardIndex);
+  const after = segments.slice(wildcardIndex + 1);
+  const wildcardBase = join(baseDir, ...before);
+  try {
+    const entries = await readdir(wildcardBase, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => join(wildcardBase, entry.name, ...after));
+  } catch (err) {
+    if (err?.code === "ENOENT") return [];
+    console.warn("[storage] legacy candidate scan skipped:", wildcardBase, err.message);
+    return [];
+  }
+}
+
+async function countFiles(dir) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    let count = 0;
+    for (const entry of entries) {
+      if (entry.name === ".trash") continue;
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) count += await countFiles(fullPath);
+      else if (entry.isFile()) count += 1;
+    }
+    return count;
+  } catch (err) {
+    if (err?.code === "ENOENT") return 0;
+    throw err;
+  }
+}
+
+async function isDirectory(dir) {
+  try {
+    return (await stat(dir)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function uniqueResolvedCandidates(candidates) {
+  return Array.from(new Set(candidates.filter(Boolean).map((p) => resolve(p))));
+}
+
+function labelPath(targetPath, env = process.env) {
+  const home = env.IMA2_TEST_HOME || homedir();
+  const resolved = resolve(targetPath);
+  const resolvedHome = resolve(home);
+  if (resolved === resolvedHome) return "~";
+  if (resolved.startsWith(resolvedHome + sep)) return `~${sep}${resolved.slice(resolvedHome.length + 1)}`;
+  return resolved;
 }
 
 function getGlobalPrefixCandidates({ env, execPath, argv1 }) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ima2-gen",
-  "version": "1.0.10",
-  "description": "GPT Image 2 generator with OAuth & API key support",
+  "version": "1.1.0",
+  "description": "Local OAuth image generation studio with classic and node workflows",
   "type": "module",
   "bin": {
     "ima2": "./bin/ima2.js"
@@ -39,6 +39,7 @@
     "lib/",
     "routes/",
     "ui/dist/",
+    "docs/",
     "assets/",
     "server.js",
     "config.js",