@duyquangnvx/image-gen 0.0.0-stage → 0.13.0

package/README.md

@@ -1,3 +1,214 @@
-# Temporary Holding Version
+# image-gen
 
-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.
+Generate, edit and cut out images through the AI SDK v7 `generateImage` surface, as a TypeScript
+library and as an `image-gen` command. You bring the model; image-gen refuses what a provider would
+quietly drop and throws when an image comes back as less than was asked for
+([ADR-0001](./docs/adr/0001-prescribe-provider-options-and-throw-rather-than-degrade.md)).
+
+[`CONTEXT.md`](./CONTEXT.md) holds the vocabulary, [`docs/design/library.md`](./docs/design/library.md)
+the shape, [`docs/adr/`](./docs/adr/) the decisions, [`docs/recipes/`](./docs/recipes/) conventions
+left out of the library, and [`CHANGELOG.md`](./CHANGELOG.md) what each release changed.
+`CONTEXT.md` and `docs/` live in the source repository, not in the npm package.
+
+## Install
+
+Node 22.12 or later.
+
+```sh
+npm i -g @duyquangnvx/image-gen && image-gen skill install   # the CLI, and its skill for Claude Code
+```
+
+For the library: `pnpm add @duyquangnvx/image-gen ai`.
+
+Inside Claude Code, type the CLI line as
+`! npm i -g @duyquangnvx/image-gen && image-gen skill install`: the sandbox denies writes to
+`~/.claude/skills`, and `!` runs outside it.
+
+If `image-gen doctor` reports the registry `behind` right after an install, npm answered from a
+stale cache: install again with its cache in a new folder,
+`! npm i -g @duyquangnvx/image-gen --cache "$(mktemp -d)" && image-gen skill install`.
+
+Once installed, the CLI upgrades itself to the latest release with `! image-gen update`: it asks
+npm's registry for the version tagged `latest`, installs it with the npm beside the Node that runs
+it, each npm call with a fresh cache so a stale one cannot hide a release, and has the new CLI
+reinstall its skill when the skill was installed. `update` is not tested on Windows,
+where npm may fail to replace the package the running `update` holds open; npm then rolls back, and
+the manual lines above still work.
+
+To uninstall, run `npm rm -g @duyquangnvx/image-gen`, then delete the skill in
+`~/.claude/skills/image-gen`, the Plan Login in `~/.codex-imagegen`, and the keys in
+`~/.config/image-gen/.env`.
+
+`@ai-sdk/openai` and `@ai-sdk/google` ship with it; add `@ai-sdk/fal` for that provider. From a
+clone, `pnpm install && pnpm build` builds `dist/`, and `pnpm link --global` then puts it on `PATH`.
+
+## Library
+
+```ts
+import { openai } from "@ai-sdk/openai"
+import { edit, generate } from "@duyquangnvx/image-gen"
+import { readImage, writeImage } from "@duyquangnvx/image-gen/node"
+
+const model = openai.image("gpt-image-2.5-flare")
+
+const { image } = await generate({ model, prompt: "a ceramic coffee mug on a linen cloth", aspectRatio: "3:2" })
+await writeImage("mug.png", image.uint8Array)   // refuses an existing file unless { force: true }
+
+// An Edit changes one target and keeps what the instruction did not name.
+// References are material to draw from, not things to modify.
+await edit({
+  model,
+  target: await readImage("portrait.png"),
+  instruction: "put the hat from image 2 on the person",
+  references: [await readImage("hat.png")],
+})
+```
+
+`generate`, `edit` and `removeBackground` return the images, the `modelId` that answered, `sizes`
+measured from the bytes, `usage` and `warnings`. Their `onResend` (the `CallHooks` type) is called
+with the `attempt` each time the AI SDK sends a failed call again, so a caller can say it is waiting.
+
+`edit` returns the model's pixels as they came back, and a model may repaint beyond what was asked,
+even beyond a Mask. `confineTo(target, { mask })` or `confineTo(target, { region })` builds, before
+sending, the function that keeps an edited image of the target's size identical to the target outside
+that Mask, or outside that rectangle and a fading band an eighth of its shorter side wide around it;
+a Region is never sent, so it holds on any model.
+
+### Transparency
+
+Three ways to get an alpha channel, which are three different things
+([ADR-0002](./docs/adr/0002-chroma-cutout-and-background-removal-stay-separate.md)):
+
+```ts
+import { fal } from "@ai-sdk/fal"
+import { google } from "@ai-sdk/google"
+import { generateCutout, removeBackground } from "@duyquangnvx/image-gen"
+
+// The model paints onto an empty background: gpt-image-1*, gpt-image-2.5 and the ChatGPT plan.
+await generate({ model: openai.image("gpt-image-2.5-flare"), prompt: "…", transparent: true })
+
+// Generate on a flat Chroma Backdrop and key it out locally, on any model. Pick a colour the subject cannot contain.
+const cutout = await generateCutout({ model: google.image("gemini-3.1-flash-image"), prompt: "a green frog", backdrop: "#ff00ff" })
+
+// Cut a subject out of a photograph you did not generate. Costs a model call.
+await removeBackground({ model: fal.image("fal-ai/bria/background/remove"), image: await readImage("photo.jpg") })
+```
+
+A cutout cannot tell you whether it worked. `inspectCutout` reports the alpha at the four corners
+(all `0` when no backdrop survived) and the Subject Bounds; `overCheckerboard` puts the image on a
+known ground to judge its edge by eye; `fitToFrame` trims it to its subject and scales that whole,
+centred, into a Target Frame; `splitPieces` separates an image holding several parts, such as a
+kit, into one cropped image per Piece, reporting the specks it drops. None of them calls a model.
+
+To hold one character across poses, see the [consistent-character recipe](./docs/recipes/consistent-character.md)
+and `variantPrompt`.
+
+### On a ChatGPT plan
+
+`@duyquangnvx/image-gen/codex` is a model that posts to the ChatGPT plan's Images route, the one
+Codex CLI calls, so generation bills the plan instead of API credit. Personal use only
+([ADR-0004](./docs/adr/0004-the-codex-model-calls-the-plan-images-route-directly.md)). It keeps its
+own login in `~/.codex-imagegen`, apart from your Codex CLI's. Sign in once, through the Codex CLI:
+
+```sh
+image-gen login
+```
+
+```ts
+import { codex } from "@duyquangnvx/image-gen/codex"
+
+await generate({ model: codex.image(), prompt: "a ceramic coffee mug", transparent: true })
+```
+
+The route always paints `gpt-image-2` at about 1536×1024, so only the shape can be chosen, and it is
+written into the prompt ([ADR-0005](./docs/adr/0005-the-codex-model-writes-the-requested-shape-into-the-prompt.md)).
+It takes at most five images per call, as bytes, and no Mask.
+
+### What it throws
+
+Every error of its own is an `ImageGenError` carrying facts, not advice
+([ADR-0006](./docs/adr/0006-library-errors-carry-facts-and-the-core-classifies-provider-failures.md)).
+
+| Error | When |
+|---|---|
+| `RefusalError`: `WrongModelKindError`, `UnsupportedRequestError` | before anything is sent, for a request that would fail silently: a shape, transparency, Mask or `quality` the model cannot give, an input over 50MB. `reason` names the cause |
+| `RequestDegradedError`: `ProviderWarnedError`, `WrongSizeError` | the provider warned, or an exact `size` came back as another. `result` holds the billed images, and `failures` each position of the batch no image came back for, empty when none failed; `allowWarnings: true` returns the images instead, or throws `PartialResultError` when some failed ([ADR-0008](./docs/adr/0008-a-degraded-result-is-thrown-with-its-images.md), [ADR-0012](./docs/adr/0012-a-batch-exits-by-whoever-must-act-first.md)) |
+| `PartialResultError` | some calls of a request for several images failed, or were aborted: `result` holds the ones that came back, `failures` each missing position with its failure or the abort, and `cause` the first of them ([ADR-0007](./docs/adr/0007-a-partial-result-is-thrown-with-the-images-that-came-back.md), [ADR-0012](./docs/adr/0012-a-batch-exits-by-whoever-must-act-first.md)) |
+| `NoResultError` | every call of a request split over several failed or was aborted, so no image came back: `failures` holds each position with its failure or the abort, `cause` the first of them; a request sent as one call throws that call's own error instead ([ADR-0012](./docs/adr/0012-a-batch-exits-by-whoever-must-act-first.md)) |
+| `ProviderFailedError` | the provider refused, could not be reached, or left an Unanswered Request, which may have been billed and is never resent ([ADR-0011](./docs/adr/0011-an-unanswered-request-is-never-resent.md)): `provider`, `answer`, and `reach`, one of `answered` (with `status` and `retryable`), `unreached`, `unanswered`, or `refreshUnanswered` (the plan's token refresh got no answer, before anything was billed) |
+| `QuotaExhaustedError` | the plan's quota or an account's credit ran out: `provider`, `limit`, `resetsAt` |
+| `LoginRequiredError` | from `@duyquangnvx/image-gen/codex`: the plan has no login; `command` is the fix |
+| `LoginDeniedError` | from `@duyquangnvx/image-gen/codex`: the file system, often a sandbox, refuses to read the login, or to save a lapsed one's refresh in its directory `home`, which is checked before the refresh token is spent |
+| `UnconfinableEditError`, `UnfittableImageError`, `UnsplittableImageError` | `confineTo()`, `fitToFrame()` or `splitPieces()` was given input it cannot work on; `reason` says why |
+| `NoImageGeneratedError` | from `ai`: the model answered without an image, usually a content filter |
+
+## Command line
+
+```sh
+image-gen generate "a knight in silver armour, full length" --out knight.png --transparent
+cat prompt.txt | image-gen generate - --out hero.png --ref sketch.png --n 3   # hero-1.png … hero-3.png
+image-gen edit knight.png "give him a red cape" --out caped.png --ref cape.png
+image-gen edit hero.png "fix his face" --out hero-2.png --region 120,40,96,96   # the face changes; past a 12 px fade around it, nothing does
+image-gen generate "a green frog" --out frog.png --model google:gemini-3.1-flash-image --cutout --backdrop '#ff00ff'
+image-gen cutout frog.plate.png --out frog-2.png --contract 1   # re-key the plate, no model call
+image-gen fit frog.png --frame 392x180 --out frog-392.png       # no model call
+image-gen split kit.png --out-dir pieces                        # kit-01.png, kit-02.png … one per Piece, no model call
+image-gen contact-sheet frog.png frog-2.png --out cmp.png       # compare in one look, no model call
+image-gen doctor   # the pinned model, every provider's key or login, and the latest release, billing nothing
+```
+
+`image-gen <command> --help` lists each command's flags.
+
+**Who pays.** `--model provider:id` picks the model and who is billed: `openai:<id>` bills
+`OPENAI_API_KEY`, `codex:gpt-image-2` the ChatGPT plan, `google:<gemini-id>`
+`GOOGLE_GENERATIVE_AI_API_KEY`. Keys are read from the shell, or else `~/.config/image-gen/.env`.
+Without `--model`, a run takes the model pinned by the nearest `image-gen.json`
+(`{ "model": "codex:gpt-image-2" }`); with neither, it is refused before anything is sent. Every
+run's last line says who was billed. `openai` sends `--option quality=medium` unless told otherwise,
+since each step up costs several times more; the plan picks its own quality.
+
+**What it writes.** `--out` is always a PNG, and an existing file is refused before anything is
+billed, unless `--force` replaces it or `--resume` keeps it. Each image a model call wrote gets a
+Provenance Record beside it, `knight.png.json`, holding the full prompt, input hashes, model, options
+and warnings; `--resume` keeps an image whose record says this run asked for it, and sends only for
+the rest. Images billed before a failure are still written. Every `data.images` entry has the same
+keys: `kept` is `true` for an image `--resume` kept and `false` for one this run billed, `provenance`
+is `null` for a record that could not be written, and a `--cutout` plate whose keyed image could not
+be written has `null` for everything but `plate` and `kept`.
+
+**For agents.** `--json` prints exactly one envelope on stdout; a failure carries a stable `code`, a
+`hint` naming the next command, and `details`. A plan call takes 30–145 s and gets up to 270 s, less when the
+run's 9 minutes are nearly used, so that the whole run, writes included, ends within them; the
+`E_NO_ANSWER` message gives the time the call actually had. A run with under 10 s left for its call
+does not send it (`E_TIMEOUT`). Give the tool a timeout of 10 minutes.
+Ctrl-C stops a run from sending more, but lets the calls already sent finish and writes their images.
+[`skills/image-gen/`](./skills/image-gen/SKILL.md) is a Claude Code skill for driving the CLI; it
+ships in the package, `image-gen skill install` copies it to
+`~/.claude/skills/image-gen`, and `image-gen doctor` says whether that copy matches the installed CLI.
+
+| Exit | Who acts (repo-harness ADR 0002) |
+|---|---|
+| 0 | done |
+| 1 | the caller fixes its command (a flag, an argument, a file, a request the model refuses or degrades, a run whose 9 minutes passed, or left under 10 s for its call, before sending: `E_TIMEOUT`) |
+| 2 | the operator acts on their machine (a key, `E_TOKEN_REJECTED`, the Plan Login, `E_OUT_OF_CREDIT`, the sandbox, a request that may have been billed with no answer back, within the time it had or at all: `E_NO_ANSWER`, or an `update` that npm, the registry's credentials or the new CLI's `skill install` refused) |
+| 3 | someone at the source acts (`E_NO_LATEST`: the registry names no release to update to) |
+| 70 | a bug in image-gen |
+| 75 | nobody acts: wait, then run it again (the plan's quota, until `details.retryAt` when known; a provider failing for now, `E_HTTP_TRANSIENT`, a provider or the registry never reached, `E_NETWORK`, `E_REGISTRY_UNREACHABLE`; a plan token refresh that got no answer, `E_LOGIN_NO_ANSWER`) |
+| 130, 143 | interrupted |
+
+## Scripts
+
+| | |
+|---|---|
+| `pnpm test` | vitest, no network, no keys |
+| `pnpm typecheck` | `tsc --noEmit` |
+| `pnpm lint` | Biome, warnings fail |
+| `pnpm build` | tsdown; also runs on `npm pack` via `prepack` |
+| `pnpm e2e` | live, 5 Gemini calls: the three-tier character run |
+| `pnpm e2e:codex` | live, 1 plan call: proves the route is up |
+| `pnpm e2e:google` | live, 2 Gemini calls through the built CLI |
+| `pnpm e2e:pipeline` | live, 6 plan calls: the reference pipeline |
+| `pnpm release` | tags and publishes to npmjs: [`docs/agents/release.md`](./docs/agents/release.md) |
+
+Gemini scripts need `GOOGLE_GENERATIVE_AI_API_KEY` in `.env.local`. Live scripts write to the
+git-ignored `out/<timestamp>/`.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}