pixelmuse 0.2.0

package/LICENSE

@@ -0,0 +1,88 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             StarMorph LLC
+Licensed Work:        Pixelmuse CLI 0.2.0
+                      The Licensed Work is (c) 2025 StarMorph LLC.
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided that you do not use the Licensed Work to
+                      offer a commercial image generation service that
+                      competes with or substitutes for the Licensor's
+                      image generation products and services.
+Change Date:          2029-03-01
+Change License:       GNU General Public License v2.0 or later
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create
+derivative works, redistribute, and make non-production use of the
+Licensed Work. The Licensor may make an Additional Use Grant, above,
+permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first
+publicly available distribution of a specific version of the Licensed
+Work under this License, whichever comes first, the Licensor hereby
+grants you rights under the terms of the Change License, and the rights
+granted in the paragraph above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or
+authorized resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative
+works of the Licensed Work, are subject to this License. This License
+applies separately for each version of the Licensed Work and the Change
+Date may vary for each version of the Licensed Work released by
+Licensor.
+
+You must conspicuously display this License on each original or modified
+copy of the Licensed Work. If you receive the Licensed Work in original
+or modified form from a third party, the terms and conditions set forth
+in this License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will
+automatically terminate your rights under this License for the current
+and all other versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or
+logo of Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS
+PROVIDED ON AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES
+AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION)
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to
+license your works, and to refer to it using the trademark "Business
+Source License", as long as you comply with the Covenants of Licensor
+below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the
+"Business Source License" name and trademark, Licensor covenants to
+MariaDB, and to all other recipients of the licensed work to be provided
+by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later
+   version, or a license that is compatible with GPL Version 2.0 or a
+   later version, where "compatible" means that software provided under
+   the Change License can be included in a program with software
+   provided under GPL Version 2.0 or a later version. Licensor may
+   specify additional Change Licenses without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does
+   not impose any additional restriction on the right granted in this
+   License, as the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights
+Reserved. "Business Source License" is a trademark of MariaDB
+Corporation Ab.

package/README.md

@@ -0,0 +1,274 @@
+<p align="center">
+  <img src="./assets/banner.png" alt="pixelmuse" width="700" />
+</p>
+
+<p align="center">
+  <strong>AI image generation from the terminal.</strong><br/>
+  CLI, interactive TUI, and MCP server — powered by the <a href="https://pixelmuse.studio">Pixelmuse</a> API.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/pixelmuse"><img src="https://img.shields.io/npm/v/pixelmuse.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/pixelmuse"><img src="https://img.shields.io/npm/dm/pixelmuse.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/starmorph/pixelmuse-cli/actions/workflows/ci.yml"><img src="https://github.com/starmorph/pixelmuse-cli/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/starmorph/pixelmuse-cli/actions/workflows/security.yml"><img src="https://github.com/starmorph/pixelmuse-cli/actions/workflows/security.yml/badge.svg" alt="Security" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-BSL%201.1-blue.svg" alt="License: BSL 1.1" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js" /></a>
+</p>
+
+---
+
+<!-- GIF: Hero — basic generation. Record: pixelmuse "a cyberpunk city at sunset, neon lights reflecting on wet streets" -->
+<!-- Replace this comment with: <p align="center"><img src="YOUR_GIF_URL" alt="Pixelmuse CLI demo" width="600" /></p> -->
+
+---
+
+## Why Pixelmuse?
+
+- **One command, any model.** Flux, Imagen 3, Recraft V4, and more — switch models with a flag, no separate accounts or API keys.
+- **Built for developer workflows.** Pipe from stdin, JSON output for scripting, watch mode for prompt iteration, MCP server for AI agents.
+- **Predictable credit pricing.** 1-3 credits per generation, no surprises. Free credits on signup.
+
+## Install
+
+```bash
+npm install -g pixelmuse
+```
+
+Then authenticate:
+
+```bash
+pixelmuse login
+```
+
+Sign up at [pixelmuse.studio/sign-up](https://www.pixelmuse.studio/sign-up) — new accounts include free credits.
+
+> Requires Node.js 20+. For terminal image previews, install [chafa](https://hpjansson.org/chafa/) (`brew install chafa` / `sudo apt install chafa`).
+
+## Quick Start
+
+```bash
+# Generate an image
+pixelmuse "a cat floating through space"
+
+# Choose model and aspect ratio
+pixelmuse "neon cityscape at night" -m recraft-v4 -a 16:9
+
+# Apply a style
+pixelmuse "mountain landscape" -s anime -a 21:9
+
+# Save to specific path
+pixelmuse "app icon, minimal" -o icon.png
+```
+
+<!-- GIF: Model selection. Record: pixelmuse "a cat astronaut" -m recraft-v4 --open -->
+<!-- Replace this comment with: <p align="center"><img src="YOUR_GIF_URL" alt="Model selection" width="600" /></p> -->
+
+## Prompt Templates
+
+Save reusable prompts as YAML files with variables and default settings.
+
+```bash
+# Scaffold a new template
+pixelmuse template init product-shot
+
+# Generate with a template
+pixelmuse template use blog-thumbnail --var subject="React hooks guide"
+
+# List all templates
+pixelmuse template list
+```
+
+<!-- GIF: Template system. Record: pixelmuse template use blog-thumbnail --var subject="TypeScript generics" -->
+<!-- Replace this comment with: <p align="center"><img src="YOUR_GIF_URL" alt="Template system" width="600" /></p> -->
+
+Templates are stored at `~/.config/pixelmuse-cli/prompts/`:
+
+```yaml
+# blog-thumbnail.yaml
+name: Blog Thumbnail
+description: Dark-themed blog post thumbnail
+prompt: >
+  A cinematic {{subject}} on a dark gradient background,
+  dramatic lighting, 8K resolution
+defaults:
+  model: nano-banana-2
+  aspect_ratio: "16:9"
+variables:
+  subject: "code editor with syntax highlighting"
+tags: [blog, thumbnail, dark]
+```
+
+## Interactive TUI
+
+A full terminal UI for visual browsing, generation wizards, gallery, and account management:
+
+```bash
+pixelmuse ui
+```
+
+<!-- GIF: TUI. Record: pixelmuse ui → navigate Generate → pick model → type prompt → generate -->
+<!-- Replace this comment with: <p align="center"><img src="YOUR_GIF_URL" alt="Interactive TUI" width="600" /></p> -->
+
+## Scripting & Pipes
+
+```bash
+# Pipe prompt from stdin
+echo "hero banner for SaaS landing page" | pixelmuse -o hero.png
+cat prompt.txt | pixelmuse -m recraft-v4
+
+# JSON output for scripting
+pixelmuse --json "logo concept" | jq .output_path
+
+# Watch mode — regenerates when prompt file changes
+pixelmuse --watch prompt.txt -o output.png
+
+# Skip preview, copy to clipboard
+pixelmuse "avatar" --no-preview --clipboard
+```
+
+<!-- GIF: Pipe/scripting. Record: echo "minimalist logo for a coffee shop" | pixelmuse --json -m flux-schnell -->
+<!-- Replace this comment with: <p align="center"><img src="YOUR_GIF_URL" alt="Scripting and pipes" width="600" /></p> -->
+
+## MCP Server (Claude Code, Cursor, Windsurf)
+
+The MCP server lets AI agents generate images, list models, and check your balance — no manual CLI steps needed.
+
+**Claude Code** — add to `~/.claude/.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "pixelmuse": {
+      "command": "npx",
+      "args": ["-y", "pixelmuse-mcp"],
+      "env": {
+        "PIXELMUSE_API_KEY": "pm_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+**Cursor / Windsurf** — add to your MCP settings:
+
+```json
+{
+  "pixelmuse": {
+    "command": "npx",
+    "args": ["-y", "pixelmuse-mcp"],
+    "env": {
+      "PIXELMUSE_API_KEY": "pm_live_your_key_here"
+    }
+  }
+}
+```
+
+The agent gets three tools:
+
+| Tool | What it does |
+|------|-------------|
+| `generate_image` | Generate an image from a prompt with model, aspect ratio, style, and output path. |
+| `list_models` | List all available models with credit costs. |
+| `check_balance` | Check your credit balance and plan info. |
+
+**Example prompts for your AI agent:**
+
+- "Generate a hero image for my landing page, 16:9, save to `./public/hero.png`"
+- "Create a blog thumbnail about React hooks using the anime style"
+- "What Pixelmuse models are available?"
+
+## Which Interface?
+
+Pixelmuse ships four interfaces. Pick the one that fits your workflow — they all use the same API and credentials.
+
+| | **CLI** | **TUI** | **MCP Server** | **Claude Skill** |
+|---|---|---|---|---|
+| **What it is** | Command-line tool | Interactive terminal UI | AI agent tool server | Claude Code prompt template |
+| **Launch** | `pixelmuse "prompt"` | `pixelmuse ui` | Auto-starts with Claude/Cursor | Auto-triggers on keywords |
+| **Best for** | Scripting, automation, CI/CD | Visual browsing, exploring models | Letting AI agents generate images | Generating images mid-conversation |
+| **Input** | Flags, stdin, pipe, watch mode | Guided wizard with menus | AI decides params from natural language | Natural language to Claude |
+
+**Rule of thumb:**
+- **You type the prompt** → CLI or TUI
+- **AI types the prompt** → MCP Server or Claude Skill
+- **Quick one-off** → CLI
+- **Browsing/exploring** → TUI
+
+## Models
+
+| Model | Credits | Best For |
+|-------|---------|----------|
+| **Nano Banana 2** (default) | 1 | Speed, text rendering, world knowledge |
+| Nano Banana Pro | 4 | Text rendering, real-time info, multi-image editing |
+| Flux Schnell | 1 | Quick mockups, ideation |
+| Google Imagen 3 | 1 | Realistic photos, complex compositions |
+| Recraft V4 | 1 | Typography, design, composition |
+| Recraft V4 Pro | 7 | High-res design, art direction |
+
+## CLI Reference
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `pixelmuse "prompt"` | Generate an image (default command) |
+| `pixelmuse models` | List available models with costs |
+| `pixelmuse account` | Account balance and usage stats |
+| `pixelmuse history` | Recent generations table |
+| `pixelmuse open <id>` | Open a generation in system viewer |
+| `pixelmuse login` | Authenticate with API key |
+| `pixelmuse logout` | Remove stored credentials |
+| `pixelmuse template <cmd>` | Manage prompt templates |
+| `pixelmuse ui` | Launch interactive TUI |
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `-m, --model` | Model ID (default: `nano-banana-2`) |
+| `-a, --aspect-ratio` | Aspect ratio (default: `1:1`) |
+| `-s, --style` | `realistic`, `anime`, `artistic`, `none` |
+| `-o, --output` | Output file path |
+| `--json` | Machine-readable JSON output |
+| `--no-preview` | Skip terminal image preview |
+| `--open` | Open result in system viewer |
+| `--clipboard` | Copy image to clipboard |
+| `--watch <file>` | Watch prompt file, regenerate on save |
+| `--no-save` | Don't save image to disk |
+
+## Configuration
+
+Settings at `~/.config/pixelmuse-cli/config.yaml`:
+
+```yaml
+defaultModel: nano-banana-2
+defaultAspectRatio: "1:1"
+defaultStyle: none
+autoPreview: true
+autoSave: true
+```
+
+| Path | Contents |
+|------|----------|
+| `~/.config/pixelmuse-cli/config.yaml` | User settings |
+| `~/.config/pixelmuse-cli/auth.json` | API key (fallback if keychain unavailable) |
+| `~/.config/pixelmuse-cli/prompts/` | Prompt template YAML files |
+| `~/.local/share/pixelmuse-cli/generations/` | Auto-saved generation images |
+
+## Links
+
+- [Pixelmuse](https://www.pixelmuse.studio) — Platform home
+- [Sign up](https://www.pixelmuse.studio/sign-up) — Create an account (free credits included)
+- [API keys](https://www.pixelmuse.studio/settings/api-keys) — Manage API keys
+- [API docs](https://www.pixelmuse.studio/developers) — Full API reference (Scalar)
+- [Get credits](https://www.pixelmuse.studio/get-credits) — Buy credit packs
+<!-- - [YouTube demo](YOUR_YOUTUBE_URL) — Full walkthrough video -->
+
+## License
+
+Business Source License 1.1 (BSL 1.1). See [LICENSE](./LICENSE) for details.
+
+Free for any use except offering a competing image generation API or platform. Converts to GPL-2.0 on 2029-03-01.
+
+Copyright 2025 StarMorph LLC.

package/dist/chunk-743CKPHW.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import {
+  pollGeneration,
+  slugify
+} from "./chunk-ZVJQFWUI.js";
+import {
+  autoSave,
+  imageToBuffer,
+  saveImage
+} from "./chunk-MZZY4JXW.js";
+
+// src/core/generate.ts
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+function resolveOutputPath(prompt, output) {
+  if (output) return resolve(output);
+  const base = slugify(prompt).slice(0, 60) || "generation";
+  let filename = `${base}.png`;
+  let counter = 2;
+  while (existsSync(join(process.cwd(), filename))) {
+    filename = `${base}-${counter}.png`;
+    counter++;
+  }
+  return join(process.cwd(), filename);
+}
+async function generateImage(client, options) {
+  const {
+    prompt,
+    model = "nano-banana-2",
+    aspectRatio = "1:1",
+    style,
+    output,
+    noSave = false,
+    onProgress
+  } = options;
+  const start = Date.now();
+  let gen = await client.generate({
+    prompt,
+    model,
+    aspect_ratio: aspectRatio,
+    style: style === "none" ? void 0 : style
+  });
+  if (gen.status === "processing" || gen.status === "pending") {
+    gen = await pollGeneration(client, gen.id, { onProgress });
+  }
+  const elapsed = (Date.now() - start) / 1e3;
+  let imagePath = null;
+  if (gen.output?.[0] && !noSave) {
+    const buf = await imageToBuffer(gen.output[0]);
+    const outPath = resolveOutputPath(prompt, output);
+    saveImage(buf, outPath);
+    imagePath = outPath;
+    autoSave(gen.id, buf);
+  }
+  return { generation: gen, imagePath, elapsed };
+}
+
+export {
+  generateImage
+};

package/dist/chunk-7ARYEFAH.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+// src/core/config.ts
+import envPaths from "env-paths";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import YAML from "yaml";
+var paths = envPaths("pixelmuse-cli");
+var PATHS = {
+  config: paths.config,
+  data: paths.data,
+  auth: join(paths.config, "auth.json"),
+  settings: join(paths.config, "config.yaml"),
+  prompts: join(paths.config, "prompts"),
+  generations: join(paths.data, "generations")
+};
+var DEFAULT_SETTINGS = {
+  defaultModel: "nano-banana-2",
+  defaultAspectRatio: "1:1",
+  defaultStyle: "none",
+  autoPreview: true,
+  autoSave: true
+};
+function ensureDirs() {
+  for (const dir of [PATHS.config, PATHS.data, PATHS.prompts, PATHS.generations]) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+function readSettings() {
+  ensureDirs();
+  if (!existsSync(PATHS.settings)) {
+    writeSettings(DEFAULT_SETTINGS);
+    return DEFAULT_SETTINGS;
+  }
+  try {
+    const raw = readFileSync(PATHS.settings, "utf-8");
+    return { ...DEFAULT_SETTINGS, ...YAML.parse(raw) };
+  } catch {
+    return DEFAULT_SETTINGS;
+  }
+}
+function writeSettings(settings) {
+  ensureDirs();
+  writeFileSync(PATHS.settings, YAML.stringify(settings), "utf-8");
+}
+
+export {
+  PATHS,
+  ensureDirs,
+  readSettings,
+  writeSettings
+};

package/dist/chunk-MZZY4JXW.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import {
+  PATHS
+} from "./chunk-7ARYEFAH.js";
+
+// src/core/image.ts
+import { execSync } from "child_process";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+var _chafaAvailable = null;
+function hasChafa() {
+  if (_chafaAvailable !== null) return _chafaAvailable;
+  try {
+    execSync("chafa --version", { stdio: "ignore" });
+    _chafaAvailable = true;
+  } catch {
+    _chafaAvailable = false;
+  }
+  return _chafaAvailable;
+}
+async function imageToBuffer(output) {
+  if (output.startsWith("data:")) {
+    const base64 = output.split(",", 2)[1];
+    if (!base64) throw new Error("Invalid data URI: missing base64 content");
+    return Buffer.from(base64, "base64");
+  }
+  const res = await fetch(output);
+  if (!res.ok) throw new Error(`Failed to fetch image: ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+function saveImage(buffer, path) {
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, buffer);
+  return path;
+}
+function autoSave(id, buffer) {
+  const dir = PATHS.generations;
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${id}.png`);
+  writeFileSync(path, buffer);
+  return path;
+}
+function renderImageDirect(path) {
+  if (!hasChafa()) return false;
+  try {
+    execSync(`chafa --animate off "${path}"`, {
+      stdio: "inherit",
+      maxBuffer: 10 * 1024 * 1024
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export {
+  hasChafa,
+  imageToBuffer,
+  saveImage,
+  autoSave,
+  renderImageDirect
+};