@flatkey-ai/cli 0.1.5 → 0.1.6

package/docs/superpowers/specs/2026-07-17-flatkey-cli-design.md

@@ -1,209 +0,0 @@
-# Flatkey CLI Design
-
-## Goal
-
-Build `@flatkey-ai/cli`, a cross-platform npm CLI for media workers and AI agents to use Flatkey as the most cost-effective practical AI API entrypoint for image, video, and audio generation. The CLI should make cost, credits, model choice, upload inputs, generation jobs, and saved artifacts visible from the terminal.
-
-## Scope
-
-The CLI provides:
-
-- Image generation.
-- Video generation.
-- Audio generation.
-- Cost estimation before generation.
-- Generation job creation, listing, inspection, and waiting.
-- Uploads for local image, video, and audio inputs.
-- Credit balance and usage status.
-- Recent credit transactions.
-- AI-first help output.
-- Available model listing.
-- Model parameter inspection.
-- Local onboarding for a Flatkey API key.
-- A short ASCII animation during human-facing generation commands.
-
-The first implementation is a Node.js npm package. It runs on Windows, Linux, and macOS through Node. Homebrew, apt/deb, and MSI packaging are release channels around the npm package, not separate native implementations.
-
-## Package and Binary
-
-Package name: `@flatkey-ai/cli`.
-
-Primary binary: `flatkey`.
-
-The package uses ESM JavaScript and keeps runtime dependencies minimal. It should run with the current active Node LTS line and newer.
-
-## Command Surface
-
-Top-level commands:
-
-- `flatkey onboard [--api-key <key>]`
-- `flatkey image generate --prompt "<prompt>" [options]`
-- `flatkey video generate --prompt "<prompt>" [options]`
-- `flatkey audio generate --prompt "<prompt>" [options]`
-- `flatkey generate create <model> --prompt "<prompt>" [options]`
-- `flatkey generate cost <model> --prompt "<prompt>" [options]`
-- `flatkey generate get <job-id> [--json]`
-- `flatkey generate list [--type image|video|audio] [--json]`
-- `flatkey generate wait <job-id> [--json]`
-- `flatkey upload create <file> [--json]`
-- `flatkey upload list [--type image|video|audio] [--json]`
-- `flatkey credits [--json]`
-- `flatkey status [--json]`
-- `flatkey transactions [--size <count>] [--json]`
-- `flatkey models [--type image|video|audio] [--json]`
-- `flatkey models get <model> [--json]`
-- `flatkey help [--ai] [--json]`
-- `flatkey version`
-
-Shared generation options:
-
-- `--model <model>`
-- `--base-url <url>`
-- `--api-key <key>`
-- `--out <dir>`
-- `--json`
-
-Image-specific options:
-
-- `--size <width>x<height>`
-- `--aspect <ratio>`
-- `--n <count>`
-- `--quality <quality>`
-
-Video-specific options:
-
-- `--duration <seconds>`
-- `--aspect <ratio>`
-- `--fps <number>`
-
-Audio-specific options:
-
-- `--voice <voice>`
-- `--format <mp3|wav|aac|flac>`
-
-## Authentication and Config
-
-Credential resolution order:
-
-1. `--api-key`
-2. `FLATKEY_API_KEY`
-3. Saved config at `~/.config/flatkey/config.json`
-
-`flatkey onboard` writes the config file with mode `0600` where supported. Windows should ignore chmod failures.
-
-## Flatkey API Integration
-
-Default base URL: `https://router.flatkey.ai`.
-
-Image generation follows the proven `awesome-images` behavior:
-
-- OpenAI-compatible image endpoint: `POST /v1/images/generations`
-- Gemini-style Nano endpoint: `POST /v1beta/models/{model}:generateContent?key={apiKey}`
-
-The CLI should default image generation to the Nano route when `--model` is omitted or starts with `nano`, and use `/v1/images/generations` for `gpt` or `gpt-image-*`.
-
-Video, audio, cost, jobs, uploads, credits, status, transactions, and models are implemented through small provider functions with configurable endpoint paths. The initial default paths are:
-
-- `POST /v1/videos/generations`
-- `POST /v1/audio/generations`
-- `POST /v1/generations`
-- `POST /v1/generations/cost`
-- `GET /v1/generations`
-- `GET /v1/generations/{jobId}`
-- `POST /v1/uploads`
-- `GET /v1/uploads`
-- `GET /v1/credits`
-- `GET /v1/credits/transactions`
-- `GET /v1/status`
-- `GET /v1/models`
-- `GET /v1/models/{model}`
-
-If Flatkey router returns a different shape, adapters normalize results before printing or saving artifacts.
-
-## Output and Artifacts
-
-Default output directory: `flatkey-output`.
-
-Generation commands save returned files when the API returns base64 or data URLs, and print remote URLs when the API returns URLs. JSON mode prints a machine-readable payload and suppresses animation/logging.
-
-Artifact naming:
-
-- `image-01.png`
-- `video-01.mp4`
-- `audio-01.mp3`
-
-Extensions come from returned MIME types when available.
-
-## AI-First Help
-
-`flatkey help --ai` prints a compact protocol-style guide:
-
-- Required setup.
-- Commands.
-- Arguments.
-- Environment variables.
-- JSON mode contract.
-- Example calls for image, video, audio, cost, upload, job wait, credits, transactions, status, and models.
-- Error recovery instructions for missing key, unknown model, and API failure.
-
-Human `--help` remains readable but secondary.
-
-## Models
-
-`flatkey models` fetches remote model metadata when API key and network are available. If remote fetch fails, it falls back to bundled defaults:
-
-- Image: `nano-banana-pro-preview`, `nano-banana-flash`, `gpt-image-2`
-- Video: `veo-3`, `veo-3-fast`
-- Audio: `tts-1`, `gpt-4o-mini-tts`
-
-The fallback must mark `source: "bundled"` in JSON output.
-
-## ASCII Animation
-
-Human generation mode shows a short stderr animation before and during network calls. Requirements:
-
-- Uses plain ASCII only.
-- No animation in `--json`.
-- Does not corrupt stdout artifact paths.
-- Works in Windows terminals.
-- Automatically falls back to simple log lines when stderr is not a TTY.
-
-## Error Handling
-
-Errors should be short and actionable:
-
-- Missing key: explain `flatkey onboard` and `FLATKEY_API_KEY`.
-- Unknown command: point to `flatkey help --ai`.
-- HTTP failure: show API message when present, otherwise status code.
-- Save failure: show output path and filesystem error.
-
-JSON mode errors still exit non-zero and write error JSON to stderr.
-
-## Testing
-
-Use Node's built-in `node:test` and `assert/strict`.
-
-Test coverage:
-
-- Argument parsing.
-- Config read/write and env precedence.
-- Request building for image OpenAI and Nano routes.
-- Request building for video/audio/credits/status/models.
-- Artifact persistence from base64, data URL, and URL payloads.
-- JSON mode suppresses animation/logging.
-- CLI subprocess tests against local HTTP servers.
-
-## Release Channels
-
-Primary release is npm:
-
-- `npm publish --access public`
-- Users run `npx @flatkey-ai/cli` or install globally.
-
-Secondary release assets:
-
-- Homebrew formula that installs the npm package and exposes `flatkey`.
-- Debian package wrapping the npm package and generated launcher.
-- MSI package wrapping the npm package and generated Windows launcher.
-
-Release automation should be added after the CLI is working and tested.

package/flatkey-output/audio-01.mp3

@@ -1 +0,0 @@
-audio-file

package/release/deb/README.md

@@ -1,16 +0,0 @@
-# Debian Package
-
-Build `.deb` as a wrapper around the published npm package.
-
-Expected install behavior:
-
-```bash
-sudo apt-get install flatkey
-flatkey help --ai
-```
-
-Package contents:
-
-- Node runtime dependency.
-- Global install of `@flatkey-ai/cli`.
-- `/usr/bin/flatkey` launcher.

package/release/homebrew/flatkey.rb

@@ -1,16 +0,0 @@
-class Flatkey < Formula
-  desc "Flatkey media generation CLI"
-  homepage "https://github.com/flatkey-ai/flatkey-cli"
-  license "MIT"
-
-  depends_on "node"
-
-  def install
-    system "npm", "install", "-g", "@flatkey-ai/cli", "--prefix", libexec
-    bin.install_symlink Dir["#{libexec}/bin/flatkey"].first
-  end
-
-  test do
-    system "#{bin}/flatkey", "help", "--ai"
-  end
-end

package/release/msi/README.md

@@ -1,15 +0,0 @@
-# Windows MSI
-
-Build MSI as a wrapper around the published npm package.
-
-Expected install behavior:
-
-```powershell
-flatkey help --ai
-```
-
-Package contents:
-
-- Node runtime prerequisite or bundled runtime.
-- Install of `@flatkey-ai/cli`.
-- `flatkey.cmd` on PATH.

package/test/animation.test.js

@@ -1,30 +0,0 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-
-import { createAnimation } from "../src/animation.js";
-
-test("does not animate in json mode", () => {
-  let output = "";
-  const animation = createAnimation({
-    json: true,
-    stream: { isTTY: true, write: (chunk) => { output += chunk; } },
-  });
-
-  animation.start("image");
-  animation.stop();
-
-  assert.equal(output, "");
-});
-
-test("uses single log line when stderr is not a tty", () => {
-  let output = "";
-  const animation = createAnimation({
-    json: false,
-    stream: { isTTY: false, write: (chunk) => { output += chunk; } },
-  });
-
-  animation.start("video");
-  animation.stop();
-
-  assert.equal(output, "flatkey video generation started\n");
-});

package/test/api.test.js

@@ -1,282 +0,0 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-
-import {
-  FlatkeyError,
-  generateAudio,
-  generateImage,
-  generateText,
-  generateVideo,
-  getCredits,
-  getModels,
-  getStatus,
-  planImageRequest,
-  planAudioMusicRequest,
-  planTextRequest,
-  planAudioSfxRequest,
-  planVoicesRequest,
-  planVideoRequest,
-} from "../src/api.js";
-
-function fetchRecorder(responseBody = { ok: true }) {
-  const calls = [];
-  const fetch = async (url, init) => {
-    calls.push({ url, init });
-    return {
-      ok: true,
-      status: 200,
-      async arrayBuffer() {
-        return Buffer.from("binary");
-      },
-      async json() {
-        return responseBody;
-      },
-    };
-  };
-  return { fetch, calls };
-}
-
-test("builds nano image request using gemini-style route", async () => {
-  const { fetch, calls } = fetchRecorder({ candidates: [] });
-
-  await generateImage({
-    apiKey: "key",
-    baseUrl: "https://router.test",
-    prompt: "poster",
-    fetch,
-  });
-
-  assert.equal(
-    calls[0].url,
-    "https://router.test/v1beta/models/nano-banana-pro-preview:generateContent?key=key",
-  );
-  assert.equal(calls[0].init.method, "POST");
-  assert.equal(calls[0].init.headers.Authorization, "Bearer key");
-  assert.equal(calls[0].init.headers["x-goog-api-key"], "key");
-  assert.deepEqual(JSON.parse(calls[0].init.body), {
-    contents: [{ parts: [{ text: "poster" }] }],
-  });
-});
-
-test("builds OpenAI image request for gpt image models", async () => {
-  const { fetch, calls } = fetchRecorder({ data: [] });
-
-  await generateImage({
-    apiKey: "key",
-    baseUrl: "https://router.test",
-    model: "gpt-image-2",
-    prompt: "cover",
-    size: "1024x1024",
-    n: "2",
-    fetch,
-  });
-
-  assert.equal(calls[0].url, "https://router.test/v1/images/generations");
-  assert.equal(calls[0].init.headers.Authorization, "Bearer key");
-  assert.deepEqual(JSON.parse(calls[0].init.body), {
-    model: "gpt-image-2",
-    prompt: "cover",
-    size: "1024x1024",
-    n: 2,
-  });
-});
-
-test("builds video generation request", async () => {
-  const { fetch, calls } = fetchRecorder({ data: [] });
-
-  await generateVideo({
-    apiKey: "key",
-    baseUrl: "https://router.test",
-    model: "veo-3",
-    prompt: "walkthrough",
-    duration: "8",
-    aspect: "16:9",
-    fps: "24",
-    fetch,
-  });
-
-  assert.equal(calls[0].url, "https://router.test/v1/video/generations");
-  assert.deepEqual(JSON.parse(calls[0].init.body), {
-    model: "veo-3",
-    prompt: "walkthrough",
-    duration: 8,
-    aspect: "16:9",
-    fps: 24,
-  });
-});
-
-test("builds seedance2 video generation request", async () => {
-  const { fetch, calls } = fetchRecorder({ data: [] });
-
-  await generateVideo({
-    apiKey: "key",
-    baseUrl: "https://router.test",
-    model: "seedance2",
-    prompt: "newsroom b-roll",
-    fetch,
-  });
-
-  assert.equal(calls[0].url, "https://router.test/v1/video/generations");
-  assert.equal(JSON.parse(calls[0].init.body).model, "seedance2");
-});
-
-test("builds text generation request for gpt-5.5", async () => {
-  const { fetch, calls } = fetchRecorder({ choices: [{ message: { content: "copy" } }] });
-
-  await generateText({
-    apiKey: "key",
-    baseUrl: "https://router.test",
-    model: "gpt-5.5",
-    prompt: "write headline",
-    fetch,
-  });
-
-  assert.equal(calls[0].url, "https://router.test/v1/chat/completions");
-  assert.deepEqual(JSON.parse(calls[0].init.body), {
-    model: "gpt-5.5",
-    messages: [{ role: "user", content: "write headline" }],
-  });
-});
-
-test("builds audio generation request", async () => {
-  const { fetch, calls } = fetchRecorder({ data: [] });
-
-  await generateAudio({
-    apiKey: "key",
-    baseUrl: "https://router.test",
-    model: "eleven_multilingual_v2",
-    prompt: "voiceover",
-    voiceId: "voice-123",
-    stability: "0.5",
-    similarityBoost: "0.75",
-    style: "0",
-    fetch,
-  });
-
-  assert.equal(calls[0].url, "https://router.test/v1/text-to-speech/voice-123");
-  assert.deepEqual(JSON.parse(calls[0].init.body), {
-    text: "voiceover",
-    model_id: "eleven_multilingual_v2",
-    voice_settings: {
-      stability: 0.5,
-      similarity_boost: 0.75,
-      style: 0,
-    },
-  });
-});
-
-test("builds audio sfx, music, and voices requests", () => {
-  assert.equal(planAudioSfxRequest({
-    apiKey: "key",
-    baseUrl: "https://router.test",
-    prompt: "glass shattering",
-    duration: "3",
-  }).url, "https://router.test/v1/sound-generation");
-  assert.deepEqual(planAudioSfxRequest({
-    apiKey: "key",
-    baseUrl: "https://router.test",
-    prompt: "glass shattering",
-    duration: "3",
-  }).body, {
-    text: "glass shattering",
-    duration_seconds: 3,
-  });
-
-  assert.equal(planAudioMusicRequest({
-    apiKey: "key",
-    baseUrl: "https://router.test",
-    prompt: "calm ambient piano",
-    musicLengthMs: "10000",
-  }).url, "https://router.test/v1/music");
-  assert.deepEqual(planAudioMusicRequest({
-    apiKey: "key",
-    baseUrl: "https://router.test",
-    prompt: "calm ambient piano",
-    musicLengthMs: "10000",
-  }).body, {
-    prompt: "calm ambient piano",
-    music_length_ms: 10000,
-  });
-
-  assert.equal(planVoicesRequest({
-    apiKey: "key",
-    baseUrl: "https://router.test",
-  }).url, "https://router.test/v1/voices");
-});
-
-test("builds credits, status, and models requests", async () => {
-  const { fetch, calls } = fetchRecorder({});
-
-  await getCredits({ apiKey: "key", baseUrl: "https://router.test", fetch });
-  await getStatus({ apiKey: "key", baseUrl: "https://router.test", fetch });
-  await getModels({ apiKey: "key", baseUrl: "https://router.test", fetch });
-
-  assert.equal(calls[0].url, "https://router.test/v1/credits");
-  assert.equal(calls[1].url, "https://router.test/v1/status");
-  assert.equal(calls[2].url, "https://router.test/v1/available_models");
-  assert.equal(calls[0].init.headers.Authorization, "Bearer key");
-  assert.equal(calls[2].init.headers.Authorization, "Bearer key");
-});
-
-test("plans available model list request from new-api relay route", async () => {
-  const { fetch, calls } = fetchRecorder({
-    success: true,
-    object: "list",
-    data: [{ id: "gpt-5.5", object: "model", owned_by: "flatkey" }],
-  });
-
-  await getModels({ apiKey: "env-key", fetch });
-
-  assert.equal(calls[0].url, "https://console.flatkey.ai/v1/available_models");
-  assert.equal(calls[0].init.method, "GET");
-  assert.equal(calls[0].init.headers.Authorization, "Bearer env-key");
-});
-
-test("honors explicit base url for available model list request", async () => {
-  const { fetch, calls } = fetchRecorder({ success: true, object: "list", data: [] });
-
-  await getModels({ apiKey: "env-key", baseUrl: "https://router.test", fetch });
-
-  assert.equal(calls[0].url, "https://router.test/v1/available_models");
-});
-
-test("plans dry-run requests for target media models", () => {
-  assert.equal(planImageRequest({
-    apiKey: "key",
-    model: "gpt-image-2",
-    prompt: "poster",
-  }).url, "https://router.flatkey.ai/v1/images/generations");
-
-  assert.match(planImageRequest({
-    apiKey: "key",
-    model: "nano-banana-pro-preview",
-    prompt: "poster",
-  }).url, /\/v1beta\/models\/nano-banana-pro-preview:generateContent\?key=key$/);
-
-  assert.equal(planVideoRequest({
-    apiKey: "key",
-    model: "seedance2",
-    prompt: "clip",
-  }).body.model, "seedance2");
-
-  assert.equal(planTextRequest({
-    apiKey: "key",
-    model: "gpt-5.5",
-    prompt: "headline",
-  }).body.model, "gpt-5.5");
-});
-
-test("throws FlatkeyError with API message on HTTP failure", async () => {
-  const fetch = async () => ({
-    ok: false,
-    status: 402,
-    async json() {
-      return { error: { message: "credits exhausted" } };
-    },
-  });
-
-  await assert.rejects(
-    () => getCredits({ apiKey: "key", baseUrl: "https://router.test", fetch }),
-    (error) => error instanceof FlatkeyError && /credits exhausted/.test(error.message),
-  );
-});

package/test/artifacts.test.js

@@ -1,108 +0,0 @@
-import assert from "node:assert/strict";
-import { mkdtemp, readFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { test } from "node:test";
-
-import { persistArtifacts } from "../src/artifacts.js";
-
-test("saves OpenAI base64 image artifacts", async () => {
-  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
-
-  const artifacts = await persistArtifacts({
-    kind: "image",
-    response: { data: [{ b64_json: Buffer.from("png-bytes").toString("base64") }] },
-    outDir,
-  });
-
-  assert.equal(artifacts.length, 1);
-  assert.match(artifacts[0].path, /image-01\.png$/);
-  assert.equal(await readFile(artifacts[0].path, "utf8"), "png-bytes");
-});
-
-test("saves data url video artifacts with mime extension", async () => {
-  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
-
-  const artifacts = await persistArtifacts({
-    kind: "video",
-    response: {
-      data: [{ url: `data:video/mp4;base64,${Buffer.from("mp4-bytes").toString("base64")}` }],
-    },
-    outDir,
-  });
-
-  assert.match(artifacts[0].path, /video-01\.mp4$/);
-  assert.equal(await readFile(artifacts[0].path, "utf8"), "mp4-bytes");
-});
-
-test("preserves remote url artifacts without downloading", async () => {
-  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
-
-  const artifacts = await persistArtifacts({
-    kind: "audio",
-    response: { data: [{ url: "https://cdn.test/audio.mp3" }] },
-    outDir,
-  });
-
-  assert.deepEqual(artifacts, [{ url: "https://cdn.test/audio.mp3" }]);
-});
-
-test("saves first artifact to explicit output path", async () => {
-  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
-  const output = join(outDir, "custom.png");
-
-  const artifacts = await persistArtifacts({
-    kind: "image",
-    response: { data: [{ b64_json: Buffer.from("custom-bytes").toString("base64") }] },
-    output,
-  });
-
-  assert.deepEqual(artifacts, [{ path: output }]);
-  assert.equal(await readFile(output, "utf8"), "custom-bytes");
-});
-
-test("adds numeric suffix for multiple artifacts with explicit output path", async () => {
-  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
-  const output = join(outDir, "custom.png");
-
-  const artifacts = await persistArtifacts({
-    kind: "image",
-    response: {
-      data: [
-        { b64_json: Buffer.from("one").toString("base64") },
-        { b64_json: Buffer.from("two").toString("base64") },
-      ],
-    },
-    output,
-  });
-
-  assert.match(artifacts[0].path, /custom\.png$/);
-  assert.match(artifacts[1].path, /custom-02\.png$/);
-  assert.equal(await readFile(artifacts[1].path, "utf8"), "two");
-});
-
-test("downloads remote url artifact when explicit output path is set", async () => {
-  const outDir = await mkdtemp(join(tmpdir(), "flatkey-artifacts-"));
-  const output = join(outDir, "clip.mp4");
-  const calls = [];
-
-  const artifacts = await persistArtifacts({
-    kind: "video",
-    response: { data: [{ url: "https://cdn.test/clip.mp4" }] },
-    output,
-    fetch: async (url) => {
-      calls.push(url);
-      return {
-        ok: true,
-        status: 200,
-        async arrayBuffer() {
-          return Buffer.from("video-bytes");
-        },
-      };
-    },
-  });
-
-  assert.deepEqual(calls, ["https://cdn.test/clip.mp4"]);
-  assert.deepEqual(artifacts, [{ path: output }]);
-  assert.equal(await readFile(output, "utf8"), "video-bytes");
-});