pop-img 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alextis59
+
+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

@@ -0,0 +1,63 @@
+# pop-img
+
+Generate an image from a prompt using the OpenAI Images API.
+
+## Install (global)
+
+```bash
+npm install -g pop-img
+```
+
+## Usage
+
+```bash
+export OPENAI_API_KEY="..."
+pop-img -o ./out.png "A cute robot barista, watercolor, soft lighting"
+```
+
+Print-only (no API call):
+
+```bash
+pop-img -o ./out.webp --dry-run "A futuristic dashboard UI"
+```
+
+Overwrite existing file:
+
+```bash
+pop-img -o ./assets/hero.png --overwrite "Cyberpunk city skyline at night"
+```
+
+## Options
+
+- `-o, --output <path>` (required) Output file path: .png, .jpg/.jpeg, .webp
+- `-m, --model <name>` Image model (default: gpt-image-1 or `$OPENAI_IMAGE_MODEL`)
+- `-s, --size <size>` 256x256 | 512x512 | 1024x1024 (default: 1024x1024)
+- `-q, --quality <quality>` low | medium | high | auto (default: auto)
+- `--background <bg>` opaque | transparent (default: opaque)
+- `--overwrite` overwrite output file if it exists
+- `--dry-run` print resolved settings, do not call the API
+- `-v, --version` output the version
+
+## Notes
+
+- This tool writes the returned base64 image or downloads a returned URL to the output file.
+
+## How to run locally (dev)
+
+From the project root:
+
+```bash
+npm install
+OPENAI_API_KEY="..." node bin/pop-img.js -o ./test.png "A cat wearing sunglasses"
+```
+
+## Publish-ready checklist
+
+- `npm login`
+- `npm publish`
+
+Or install directly from a git repo:
+
+```bash
+npm install -g .
+```

package/bin/pop-img.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { createRequire } from "module";
+import OpenAI from "openai";
+import fs from "fs";
+import path from "path";
+
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+
+function fail(msg, code = 1) {
+  console.error(`pop-img: ${msg}`);
+  process.exit(code);
+}
+
+function inferFormatFromPath(outPath) {
+  const ext = path.extname(outPath).toLowerCase();
+  if (ext === ".png") return "png";
+  if (ext === ".jpg" || ext === ".jpeg") return "jpeg";
+  if (ext === ".webp") return "webp";
+  return null;
+}
+
+function ensureDirForFile(filePath) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+async function downloadToFile(url, outPath) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    fail(`failed to download image: ${res.status} ${res.statusText}`);
+  }
+  const arrayBuffer = await res.arrayBuffer();
+  fs.writeFileSync(outPath, Buffer.from(arrayBuffer));
+}
+
+async function main() {
+  const program = new Command();
+
+  program
+    .name("pop-img")
+    .version(pkg.version, "-v, --version", "Output the version")
+    .description(
+      'Generate an image via OpenAI. Example: pop-img -o out.png "A cute robot"'
+    )
+    .argument("<prompt...>", "Text prompt for the image")
+    .requiredOption("-o, --output <path>", "Output file path (png/jpg/webp)")
+    .option(
+      "-m, --model <name>",
+      "Image model",
+      process.env.OPENAI_IMAGE_MODEL || "gpt-image-1"
+    )
+    .option(
+      "-s, --size <size>",
+      "Image size: 256x256 | 512x512 | 1024x1024",
+      "1024x1024"
+    )
+    .option(
+      "-q, --quality <quality>",
+      "Quality: low | medium | high | auto",
+      "auto"
+    )
+    .option(
+      "--background <bg>",
+      "Background: opaque | transparent (png/webp recommended)",
+      "opaque"
+    )
+    .option("--overwrite", "Overwrite output file if it exists", false)
+    .option("--dry-run", "Print resolved options, don't call the API", false)
+    .parse(process.argv);
+
+  const opts = program.opts();
+  const prompt = program.args.join(" ").trim();
+  const outPath = path.resolve(process.cwd(), opts.output);
+
+  if (!prompt) fail("missing prompt");
+  if (!process.env.OPENAI_API_KEY) {
+    fail("OPENAI_API_KEY is not set in environment");
+  }
+
+  const format = inferFormatFromPath(outPath);
+  if (!format) {
+    fail(
+      `unsupported output extension for "${outPath}". Use .png, .jpg/.jpeg, or .webp`
+    );
+  }
+
+  const allowedSizes = new Set(["256x256", "512x512", "1024x1024"]);
+  if (!allowedSizes.has(opts.size)) {
+    fail(`invalid --size "${opts.size}". Use 256x256, 512x512, or 1024x1024`);
+  }
+
+  const allowedQuality = new Set(["low", "medium", "high", "auto"]);
+  if (!allowedQuality.has(opts.quality)) {
+    fail(
+      `invalid --quality "${opts.quality}". Use low, medium, high, or auto`
+    );
+  }
+
+  const allowedBg = new Set(["opaque", "transparent"]);
+  if (!allowedBg.has(opts.background)) {
+    fail(`invalid --background "${opts.background}". Use opaque or transparent`);
+  }
+
+  if (fs.existsSync(outPath) && !opts.overwrite) {
+    fail(`output file already exists: ${outPath} (use --overwrite)`);
+  }
+
+  ensureDirForFile(outPath);
+
+  if (opts.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          prompt,
+          output: outPath,
+          model: opts.model,
+          size: opts.size,
+          quality: opts.quality,
+          background: opts.background,
+          format
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+  let result;
+  try {
+    result = await openai.images.generate({
+      model: opts.model,
+      prompt,
+      size: opts.size,
+      quality: opts.quality,
+      background: opts.background,
+      output_format: format
+    });
+  } catch (err) {
+    const msg =
+      (err && err.message) ||
+      (err && err.toString && err.toString()) ||
+      "unknown error calling OpenAI Images API";
+    fail(msg);
+  }
+
+  const data = result?.data?.[0];
+  const b64 = data?.b64_json;
+
+  if (!b64) {
+    const url = data?.url;
+    if (url) {
+      await downloadToFile(url, outPath);
+      process.stdout.write(outPath + "\n");
+      return;
+    }
+    fail("API response missing image data (b64_json)");
+  }
+
+  const buffer = Buffer.from(b64, "base64");
+  fs.writeFileSync(outPath, buffer);
+
+  process.stdout.write(outPath + "\n");
+}
+
+main().catch((e) => {
+  const msg = e?.message || String(e);
+  console.error(`pop-img: unexpected error: ${msg}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "pop-img",
+  "version": "1.0.2",
+  "description": "Simple CLI to generate images with OpenAI",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "pop-img": "bin/pop-img.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "openai": "^4.0.0"
+  }
+}