feat(generate-image): add Atlas Cloud as an optional provider

[binyangzhu000-sudo]

Summary

codev generate-image goes through the @google/genai SDK, so it needs a Google AI Studio key.
Atlas Cloud serves the same Nano Banana Pro model over its own submit-then-poll REST API, so
this adds it behind -p/--provider atlas. The default stays gemini and its code path is untouched.

No new dependency — the Atlas path uses global fetch (the package already requires Node >= 20).

Every mapping was measured, not assumed

Existing flag	On --provider atlas	Measured
-a/--aspect	maps to Atlas's aspect_ratio, honoured	1:1 → 1024×1024, 16:9 → 1376×768
-r/--resolution	no equivalent field	prints a note; the model's default resolution comes back
--ref	not supported (text-to-image only)	exits with an error pointing at --provider gemini
output file	model returns JPEG	named after its actual bytes, rename logged

The two behaviours I deliberately did not paper over:

• --resolution is not silently dropped. A note is printed, because a user asking for 4K and
  getting the default resolution with no explanation is worse than being told.
• --ref errors instead of generating. Ignoring reference images while still producing an image
  would look like success.
• The output file is renamed (output.png → output.jpg) rather than writing JPEG bytes into a
  .png. The Gemini path is unaffected.

Validation

• Live end-to-end: generated through Atlas with aspect: '16:9' → a real 685 KB JPEG at
  1376×768, saved as .jpg with the note printed. That run is also what confirms the
  aspect_ratio mapping above.
• Tests: 5 new vitest cases — missing ATLASCLOUD_API_KEY, unknown provider, refused --ref,
  a full submit → poll → download asserting the submitted aspect_ratio, the prediction URL, the
  explicit User-Agent and the JPEG rename, plus a failed prediction.
  vitest run src/__tests__/generate-image.test.ts → 19 passed.
• Types: tsc --noEmit reports nothing for the touched files. (There are pre-existing errors in
  src/agent-farm/*, src/commands/doctor.ts and src/lib/github.ts from unbuilt workspace deps in
  my sandbox — untouched by this PR.)

While writing the test I hit a fixture trap worth mentioning: Buffer.from([...]).buffer is a
pooled ArrayBuffer with a non-zero offset, so slicing it from 0 hands back the wrong bytes and the
JPEG-detection assertion failed for the wrong reason. The test uses new Uint8Array([...]) and says
why in a comment.

Docs

Both skeleton copies (.claude and .codex) get the new flag in the flag list plus a short
"Alternative provider" section with the measured differences. The key is an environment-variable
placeholder; no credentials in the diff.

---

🤝 Partnership & contact

This PR comes from the Atlas Cloud team. Beyond the integration above, we'd love to explore a closer collaboration with codev — for example co-marketing or a featured integration.

If that sounds interesting, reach out anytime:

• 📧 marketing@atlascloud.ai
• 🌐 https://www.atlascloud.ai
• 📚 Docs: https://www.atlascloud.ai/docs

And of course, happy to revise this PR to match your project's conventions — just leave a comment. 🙌

[waleedkadous]

Welcome, and thank you — this is a well-made first contribution: the flag-mapping table is measured rather than assumed, --resolution/--ref fail honestly instead of silently, the API key appears only in the Atlas Authorization header and never reaches the CDN fetch, and the default gemini path is untouched (all 14 existing tests pass unmodified). A few things need fixing before merge, and since they're all mechanical we'll push them onto your branch ourselves rather than send you a list (maintainer edits are enabled — thank you); your commits and authorship stay as they are. If you'd rather do them yourself, say so and we'll hold off.

What we'll change, in the spirit of the repo's fail-fast rule:

1. Skill docs: the repo's own tracked .claude/skills/generate-image/SKILL.md and .codex/skills/generate-image/SKILL.md need the same edit as the two skeleton copies (all four are meant to stay byte-identical; packages/codev/skeleton/ is generated and correctly untouched).
2. Per-request timeouts: ATLAS_TIMEOUT_MS bounds the poll loop but no individual fetch — a stalled submit, poll, or CDN download hangs forever. signal: AbortSignal.timeout(...) on all three.
3. Unknown status fails fast: the loop only exits on completed/failed, so cancelled, error, or an undefined status polls for the full 300s and then reports a misleading timeout. Allowlist the in-progress statuses and error immediately on anything else, naming it.
4. Unrecognized download bytes must not be written: withDetectedExtension currently passes unknown magic bytes through, so an HTML error body with a 200 lands in output.png under a green "Image saved". Fail instead.
5. Tests: the two polling tests sleep for real (measured 10.01s for the file; useRealTimers with no useFakeTimers) — inject the poll interval; restore the env var; and add the one assertion worth locking down: Authorization is sent to Atlas and NOT to the CDN URL.

Minor, may or may not fold in: a typeof url === 'string' guard on outputs[0], and ATLASCLOUD_API_KEY in codev/resources/cloud-instances.md for discoverability.

[waleedkadous]

Thanks again for this — it's a genuinely nice first contribution, and the parts that were hardest to get right you already got right: the flag mapping is measured against the endpoint rather than assumed, --ref and --resolution are honest about what Atlas can't do, the API key never reaches the CDN fetch, and the default Gemini path is untouched.

As offered in the review, I've pushed the mechanical fixes onto your branch rather than sending you a list. Your commit and authorship are unchanged — nothing was rebased or squashed, mine just sit on top. Here's exactly what changed and why:

1. Skill docs (all four copies). .claude/skills/generate-image/SKILL.md and .codex/skills/generate-image/SKILL.md at the repo root got the same edit you made to the two under codev-skeleton/. Easy one to miss — the repo keeps four tracked copies byte-identical, and only the two under packages/codev/skeleton/ are generated (you were right to leave those alone). I also added ATLASCLOUD_API_KEY to the frontmatter description, since that string is what an agent reads when deciding whether to use the skill.

2. Per-request timeouts. ATLAS_TIMEOUT_MS bounded the poll loop, but the loop only checks its deadline between requests — so a stalled submit, poll, or download hung forever. All three now go through an atlasRequest helper that carries AbortSignal.timeout(...).

One thing worth knowing, because it isn't obvious: the signal stays armed while the body streams, not just until the headers arrive. So the body reads had to move inside the guard too. Otherwise a poll answering 200 with an HTML error page threw a raw SyntaxError from .json(), and an abort landing on .arrayBuffer() threw a raw TimeoutError — both escaping as stack traces with no error message at all. That one came out of the review consultation and is fixed with tests.

3. Unknown statuses fail immediately. The loop only exited on completed/failed, so a cancelled or absent status polled for the full 300s and then reported a timeout — which is a lie about what happened. It now fails at once and names the status. The in-progress allowlist is processing alone: that's exactly what https://www.atlascloud.ai/docs/en/predictions documents, and I didn't want to invent plausible-looking extras.

4. Unrecognized bytes are never written. This was the one real hazard. withDetectedExtension passed unknown magic bytes through, so an HTML error body served with a 200 would land in output.png under a green "Image saved". It now exits instead. Renamed to targetPathForImageBytes, since the old name no longer described what it does.

5. Tests: 19 → 35, and the file runs in 181ms instead of ~10s. The two polling tests were sleeping for real. The poll cadence and overall budget are now parameters with the old constants as defaults, so tests can pass 0 — nothing but tests passes them. ATLASCLOUD_API_KEY is explicitly cleared per test. New cases cover submit/poll non-ok, unknown status, missing and non-string prediction id, missing and non-string image URL, unrecognized bytes, an HTML body served as JSON, a mid-stream abort, and the overall timeout. Plus the assertion worth locking down: Authorization is sent to Atlas and is not sent to the CDN.

Minor: the typeof url === 'string' guard on outputs[0] (and the same on the prediction id); ATLASCLOUD_API_KEY added to codev/resources/cloud-instances.md; the --ref refusal moved ahead of the credential check, so -p atlas --ref x without a key names the flag rather than the key.

Build and tsc --noEmit are clean, and the package suite is 5571 passing. Each fix was verified by reverting it and confirming a test fails, so none of the new tests are decorative.

One thing I deliberately did not change, because it's your call and the maintainers': a reviewer argued that -r 2K/-r 4K on the Atlas path should fail rather than print a note and continue, under the repo's fail-fast rule. There's a real argument there — it submits a billable job that can't honour the flag. But you chose the note deliberately and explained why, so I've left your behaviour intact and raised it separately rather than quietly reversing it.

Since this is a PR from a fork, CI needs a maintainer to approve the workflow run before it executes — that's a GitHub setting for first-time contributors, not anything about your code. Nothing else needed from you.

Thanks for the care you put into this, especially measuring the endpoint instead of guessing at it and writing up what you found. That made the review much easier. Hope to see more from you.

[waleedkadous]

Re-verified after the maintainer-side commits: all four tracked SKILL.md copies byte-identical; every Atlas fetch goes through one AbortSignal.timeout-guarded helper (including the response-body read, which CMAP caught was outside the guard); the in-progress status allowlist is sourced from Atlas's docs and anything else fails fast naming the status; unrecognized download bytes now refuse to write; 35 tests running in milliseconds, including the key-sent-to-Atlas-never-to-CDN assertion. On --resolution 2K/4K printing a note rather than erroring on Atlas: that was your deliberate, documented design and it stands. CI 7/7 on bfcc2bb. Approving and merging — welcome aboard, @binyangzhu000-sudo, and thank you.