1#!/usr/bin/env bun
2import { readFile, mkdir, copyFile, stat } from "node:fs/promises";
3import { homedir } from "node:os";
4import path from "node:path";
5import process from "node:process";
6import { setTimeout as delay } from "node:timers/promises";
7import { GenError, type CliOptions, type GenerateResult } from "./types.ts";
8import { runCodexExec } from "./spawn.ts";
9import { hasImageGenEvidence, verifyImageGenWasInvoked, verifyOutput } from "./validator.ts";
10import { cacheKey, lookupCache, storeCache, FileLock } from "./cache.ts";
11import { JsonLogger } from "./logger.ts";
12 
13const HELP = `codex-imagegen — generate images via Codex CLI's image_gen tool
14 
15Usage:
16  codex-imagegen --image <output.png> [--prompt <text> | --prompt-file <path>] [options]
17 
18Required:
19  --image <path>          Output PNG path
20  --prompt <text>         Prompt text (or use --prompt-file)
21  --prompt-file <path>    Read prompt from file
22 
23Options:
24  --aspect <ratio>        Aspect ratio (1:1, 16:9, 9:16, 4:3, 2.35:1). Default: 1:1
25  --ref <file>            Reference image (repeatable)
26  --timeout <ms>          Codex exec timeout in ms. Default: 300000
27  --retries <n>           Retry attempts on retryable errors. Default: 2
28  --retry-delay <ms>      Base retry delay (exponential). Default: 1500
29  --cache-dir <path>      Enable idempotency cache. Disabled by default.
30  --log-file <path>       Append JSONL log
31  -v, --verbose           Verbose stderr logging
32  -h, --help              Show this help
33 
34Stdout: single JSON line on success or failure.
35`;
36 
37const SHELL_METACHAR = /[;|&`$<>\n\r()'"]/;
38 
39function assertSafePath(label: string, value: string): void {
40  if (SHELL_METACHAR.test(value)) {
41    throw new GenError(
42      "invalid_args",
43      `${label} contains shell metacharacters and would be unsafe to interpolate into the codex instruction: ${value}`,
44      false,
45    );
46  }
47}
48 
49function parseArgs(argv: string[]): CliOptions {
50  const opts: CliOptions = {
51    prompt: "",
52    promptFile: null,
53    outputPath: "",
54    aspect: "1:1",
55    refImages: [],
56    timeoutMs: 300_000,
57    retries: 2,
58    retryDelayMs: 1500,
59    cacheDir: null,
60    logFile: null,
61    verbose: false,
62  };
63  for (let i = 0; i < argv.length; i++) {
64    const a = argv[i];
65    const next = () => argv[++i];
66    switch (a) {
67      case "--prompt": opts.prompt = next(); break;
68      case "--prompt-file": opts.promptFile = next(); break;
69      case "--image": opts.outputPath = next(); break;
70      case "--aspect": opts.aspect = next(); break;
71      case "--ref": opts.refImages.push(next()); break;
72      case "--timeout": opts.timeoutMs = Number(next()); break;
73      case "--retries": opts.retries = Number(next()); break;
74      case "--retry-delay": opts.retryDelayMs = Number(next()); break;
75      case "--cache-dir": opts.cacheDir = next(); break;
76      case "--log-file": opts.logFile = next(); break;
77      case "-v":
78      case "--verbose": opts.verbose = true; break;
79      case "-h":
80      case "--help": process.stdout.write(HELP); process.exit(0);
81      default: throw new GenError("invalid_args", `Unknown argument: ${a}`, false);
82    }
83  }
84  if (!opts.outputPath) throw new GenError("invalid_args", "--image is required", false);
85  if (opts.prompt && opts.promptFile) {
86    throw new GenError("invalid_args", "--prompt and --prompt-file are mutually exclusive", false);
87  }
88  if (!opts.prompt && !opts.promptFile) {
89    throw new GenError("invalid_args", "--prompt or --prompt-file required", false);
90  }
91 
92  // Resolve every filesystem path to absolute up front, so behavior is
93  // independent of the caller's cwd. This matters when the wrapper is
94  // invoked from a skill running in an arbitrary working directory.
95  const cwd = process.cwd();
96  const toAbs = (p: string) => (path.isAbsolute(p) ? p : path.resolve(cwd, p));
97 
98  opts.outputPath = toAbs(opts.outputPath);
99  if (opts.promptFile) opts.promptFile = toAbs(opts.promptFile);
100  opts.refImages = opts.refImages.map(toAbs);
101  if (opts.cacheDir) opts.cacheDir = toAbs(opts.cacheDir);
102  if (opts.logFile) opts.logFile = toAbs(opts.logFile);
103 
104  // The output and ref paths are interpolated raw into the agent instruction
105  // sent to `codex exec --sandbox danger-full-access`. A path containing shell
106  // metacharacters could be misread by the agent's shell when it cp's the
107  // result into place. Reject upfront rather than trusting the agent to quote.
108  assertSafePath("--image path", opts.outputPath);
109  for (const ref of opts.refImages) assertSafePath("--ref path", ref);
110 
111  return opts;
112}
113 
114async function loadPrompt(opts: CliOptions): Promise<string> {
115  if (opts.prompt) return opts.prompt;
116  const file = opts.promptFile!;
117  try {
118    return await readFile(file, "utf-8");
119  } catch {
120    throw new GenError("prompt_file_missing", `Prompt file not found: ${file}`, false);
121  }
122}
123 
124function buildInstruction(prompt: string, opts: CliOptions): string {
125  const refHint = opts.refImages.length > 0
126    ? `\nREFERENCE IMAGES (attached above): ${opts.refImages.length} image(s) provided for style/composition guidance.\n`
127    : "";
128  return `You have an internal tool called image_gen for image generation. You MUST call it before doing anything else.
129 
130TASK: Generate an image with the spec below, then save to disk.
131 
132PROMPT:
133${prompt}
134 
135ASPECT RATIO: ${opts.aspect}
136OUTPUT PATH: ${opts.outputPath}
137${refHint}
138STEPS:
1391. Call image_gen with the prompt and aspect ratio above${opts.refImages.length > 0 ? " (using the attached reference images for guidance)" : ""}.
1402. Move or copy ONLY the image produced by that image_gen call from Codex default location ($CODEX_HOME/generated_images/...) to: ${opts.outputPath}
1413. Verify with: ls -la ${opts.outputPath}
1424. Reply with ONLY this JSON line (no markdown fences, no other text):
143   {"status":"ok","path":"${opts.outputPath}","bytes":<file_size_in_bytes>}
144 
145HARD CONSTRAINTS:
146- Do NOT search for, find, inspect, reuse, or copy any pre-existing files from $CODEX_HOME/generated_images/ or any other directory.
147- Do NOT run ls/find/rg/grep/glob over $CODEX_HOME/generated_images/ before image_gen has been called.
148- You MUST call image_gen first. Only after image_gen completes may you copy the newly created file from this turn.
149- Do NOT use curl, wget, Python, or any external API.
150- Do NOT use bash to fabricate an image; only image_gen produces real pixels.
151- Use ONLY the image_gen internal tool.`;
152}
153 
154async function attemptGenerate(
155  opts: CliOptions,
156  instruction: string,
157  attempt: number,
158  log: JsonLogger,
159): Promise<{ bytes: number; threadId: string | null; usage: any; toolCalls: any[] }> {
160  await log.info("attempt.start", { attempt, output: opts.outputPath, aspect: opts.aspect });
161 
162  const run = await runCodexExec({
163    instruction,
164    timeoutMs: opts.timeoutMs,
165    refImages: opts.refImages,
166  });
167 
168  await log.info("codex.completed", {
169    duration_ms: run.durationMs,
170    thread_id: run.threadId,
171    tool_calls: run.toolCalls.length,
172    usage: run.usage,
173    raw_log: run.rawLogPath,
174  });
175 
176  // verify: thread id must be present
177  if (!run.threadId) {
178    throw new GenError("agent_refused", "No thread id in event stream");
179  }
180 
181  // verify image_gen ran in THIS thread. A PNG in this thread's
182  // generated_images dir is the real signal (image_gen does not surface as a
183  // stream item); the stream check is a forward-compatible fallback. The #185
184  // shortcut (copying an unrelated history image) yields neither.
185  const ver = await verifyImageGenWasInvoked(run.threadId);
186  if (!hasImageGenEvidence(run.toolCalls, ver.ok)) {
187    throw new GenError(
188      "no_image_gen_tool_use",
189      `image_gen was not invoked (no image_gen event in stream; ${ver.reason})`,
190    );
191  }
192 
193  // verify output
194  const { bytes } = await verifyOutput(opts.outputPath);
195 
196  return {
197    bytes,
198    threadId: run.threadId,
199    usage: run.usage,
200    toolCalls: run.toolCalls.map((tc) => ({ tool: tc.tool, status: tc.status })),
201  };
202}
203 
204async function generate(opts: CliOptions, log: JsonLogger): Promise<GenerateResult> {
205  const startEpoch = Date.now();
206  const prompt = await loadPrompt(opts);
207 
208  // Cache lookup
209  if (opts.cacheDir) {
210    const key = cacheKey(prompt, opts.aspect, opts.refImages);
211    const cached = await lookupCache(opts.cacheDir, key);
212    if (cached) {
213      await mkdir(path.dirname(opts.outputPath), { recursive: true });
214      await copyFile(cached, opts.outputPath);
215      const s = await stat(opts.outputPath);
216      await log.info("cache.hit", { key, source: cached });
217      return {
218        status: "ok",
219        path: opts.outputPath,
220        bytes: s.size,
221        elapsed_seconds: 0,
222        thread_id: null,
223        attempts: 0,
224        cached: true,
225        usage: null,
226        tool_calls: [],
227      };
228    }
229    await log.info("cache.miss", { key });
230  }
231 
232  // lock to prevent concurrent codex exec
233  const lockDir = opts.cacheDir ?? path.join(homedir(), ".cache", "baoyu-codex-imagegen");
234  const lock = new FileLock(path.join(lockDir, "codex-exec.lock"));
235  try {
236    await lock.acquire(60_000);
237  } catch (e) {
238    throw new GenError("lock_busy", String(e), false);
239  }
240 
241  await mkdir(path.dirname(opts.outputPath), { recursive: true });
242  const instruction = buildInstruction(prompt, opts);
243 
244  let lastErr: GenError | null = null;
245  let lastAttempt = 0;
246  try {
247    for (let attempt = 1; attempt <= opts.retries + 1; attempt++) {
248      lastAttempt = attempt;
249      try {
250        const result = await attemptGenerate(opts, instruction, attempt, log);
251 
252        // write to cache
253        if (opts.cacheDir) {
254          const key = cacheKey(prompt, opts.aspect, opts.refImages);
255          await storeCache(opts.cacheDir, key, opts.outputPath);
256          await log.info("cache.stored", { key });
257        }
258 
259        return {
260          status: "ok",
261          path: opts.outputPath,
262          bytes: result.bytes,
263          elapsed_seconds: Math.round((Date.now() - startEpoch) / 1000),
264          thread_id: result.threadId,
265          attempts: attempt,
266          cached: false,
267          usage: result.usage,
268          tool_calls: result.toolCalls,
269        };
270      } catch (e) {
271        lastErr = e instanceof GenError ? e : new GenError("spawn_failed", String(e));
272        await log.warn("attempt.failed", {
273          attempt,
274          kind: lastErr.kind,
275          retryable: lastErr.retryable,
276          error: lastErr.message,
277        });
278        if (!lastErr.retryable || attempt > opts.retries) break;
279        const wait = opts.retryDelayMs * Math.pow(2, attempt - 1);
280        await log.info("retry.wait", { wait_ms: wait, next_attempt: attempt + 1 });
281        await delay(wait);
282      }
283    }
284  } finally {
285    await lock.release();
286  }
287 
288  const err = lastErr ?? new GenError("spawn_failed", "Unknown failure");
289  err.attempts = lastAttempt;
290  throw err;
291}
292 
293async function main() {
294  let opts: CliOptions;
295  try {
296    opts = parseArgs(process.argv.slice(2));
297  } catch (e) {
298    const err = e instanceof GenError ? e : new GenError("invalid_args", String(e), false);
299    process.stderr.write(`Error: ${err.message}\n`);
300    process.exit(2);
301  }
302 
303  const log = new JsonLogger(opts.logFile, opts.verbose);
304  await log.info("start", { output: opts.outputPath, aspect: opts.aspect, refs: opts.refImages.length });
305 
306  try {
307    const result = await generate(opts, log);
308    await log.info("done", { bytes: result.bytes, attempts: result.attempts, cached: result.cached });
309    process.stdout.write(JSON.stringify(result) + "\n");
310    process.exit(0);
311  } catch (e) {
312    const err = e instanceof GenError ? e : new GenError("spawn_failed", String(e));
313    await log.error("failed", { kind: err.kind, error: err.message, attempts: err.attempts ?? 0 });
314    const out: GenerateResult = {
315      status: "error",
316      path: opts.outputPath,
317      bytes: 0,
318      elapsed_seconds: 0,
319      thread_id: null,
320      attempts: err.attempts ?? 0,
321      cached: false,
322      usage: null,
323      tool_calls: [],
324      error: err.message,
325      error_kind: err.kind,
326    };
327    process.stdout.write(JSON.stringify(out) + "\n");
328    process.exit(1);
329  }
330}
331 
332main();
333