imgx-cli 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+## 0.5.0 (2026-02-26)
+
+### Added
+
+- `edit_last` MCP tool — edit the last generated/edited image via MCP without specifying input path
+- `imgx init` command — create `.imgxrc` project config template in current directory
+- MCP server now tracks last output (shared with CLI `--last` flag)
+
+## 0.4.0 (2026-02-26)
+
+### Added
+
+- `--last` (`-l`) flag for `edit` command — use the previous output as input automatically
+  - Works with both `generate` and `edit` outputs
+  - Enables iterative editing without manually specifying file paths
+- `.imgxrc` project config — place in project directory for project-level defaults
+  - Supports `defaults.model`, `defaults.outputDir`, `defaults.aspectRatio`, `defaults.resolution`, `defaults.provider`
+  - Shared via Git (no API keys — use `imgx config set api-key` or env vars)
+
+### Changed
+
+- Settings resolution expanded to 5 layers: CLI flags → env vars → `.imgxrc` → user config → provider defaults
+
+## 0.3.0 (2026-02-26)
+
+### Added
+
+- `imgx config` command — manage API keys and default settings via config file
+  - `config set api-key <key>` — save Gemini API key (no more manual environment variable setup)
+  - `config set model|provider|output-dir|aspect-ratio|resolution <value>` — set defaults
+  - `config list` — show all settings
+  - `config get <key>` — show a specific setting (API key is masked)
+  - `config path` — show config file location
+- Config file at `~/.config/imgx/config.json` (Linux/macOS) or `%APPDATA%\imgx\config.json` (Windows)
+- Settings resolution: CLI flags → environment variables → config file → provider defaults
+- Uninstall instructions in README (plugin, npm, MCP, config cleanup)
+
+### Changed
+
+- API key resolution: environment variable → config file (env var still takes precedence)
+- Default model, provider, output-dir, aspect-ratio, resolution are now configurable via `imgx config set`
+
+## 0.2.0 (2026-02-26)
+
+### Added
+
+- MCP server (`dist/mcp.bundle.js`) — exposes `generate_image`, `edit_image`, `list_providers` tools via Model Context Protocol stdio transport
+- Works with Gemini CLI, Codex CLI, Antigravity, Cursor, Windsurf, Continue.dev, Cline, Zed, and any MCP-compatible tool
+- `.mcp.json` updated with actual server config for Claude Code plugin auto-registration
+- `imgx-mcp` bin command for direct MCP server execution
+
+## 0.1.0 (2026-02-26)
+
+Initial release.
+
+### Features
+
+- `generate` command: text-to-image generation
+- `edit` command: image editing with text instructions
+- `providers` command: list available providers
+- `capabilities` command: show provider capabilities
+- Gemini provider with 7 capabilities (generate, edit, aspect ratio, resolution, multi-output, reference images, person control)
+- Capability-based provider abstraction (model-independent core + model-dependent providers)
+- JSON output for scripting and tool integration
+- Single-file esbuild bundle
+
+### Distribution
+
+- Claude Code plugin: `somacoffeekyoto/imgx-cli` marketplace with `image-generation` skill
+- npm package name reserved: `imgx-cli` (publish pending)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOMA COFFEE KYOTO
+
+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,377 @@
+# imgx-cli
+
+AI image generation and editing from the terminal. Provider-agnostic design with capability-based abstraction.
+
+<!-- TODO: Add demo GIF showing generate → edit → edit --last workflow -->
+
+## Install
+
+### As a Claude Code plugin
+
+```
+/plugin marketplace add somacoffeekyoto/imgx-cli
+/plugin install imgx-cli@somacoffeekyoto-imgx-cli
+```
+
+After installation, restart Claude Code. The `image-generation` skill becomes available — Claude Code can generate and edit images via natural language instructions.
+
+### Update
+
+#### Claude Code plugin
+
+You can try updating via the plugin manager:
+
+```
+/plugin update → select "installed" → imgx-cli → update
+```
+
+If the update shows no changes or the plugin doesn't reflect the latest version, uninstall and reinstall:
+
+```
+/plugin uninstall imgx-cli@somacoffeekyoto-imgx-cli
+/plugin install imgx-cli@somacoffeekyoto-imgx-cli
+```
+
+Then restart Claude Code.
+
+#### Standalone CLI
+
+```bash
+npm update -g imgx-cli
+```
+
+### As a standalone CLI
+
+```bash
+npm install -g imgx-cli
+```
+
+Requires Node.js 18+.
+
+## Setup
+
+Get a Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey) (free tier available), then save it:
+
+```bash
+imgx config set api-key YOUR_GEMINI_API_KEY
+```
+
+This stores the key in `~/.config/imgx/config.json` (Linux/macOS) or `%APPDATA%\imgx\config.json` (Windows). Alternatively, set an environment variable:
+
+```bash
+export GEMINI_API_KEY="your-api-key"
+```
+
+Environment variables take precedence over the config file.
+
+## Usage
+
+### Generate an image from text
+
+```bash
+imgx generate -p "A coffee cup on a wooden table, morning light" -o output.png
+```
+
+### Edit an existing image
+
+```bash
+imgx edit -i photo.png -p "Change the background to sunset" -o edited.png
+```
+
+### Iterative editing with `--last`
+
+```bash
+imgx edit -i photo.png -p "Make the background darker"
+# → {"success": true, "filePaths": ["./imgx-a1b2c3d4.png"]}
+
+imgx edit --last -p "Add warm lighting"
+# Uses the previous output as input automatically
+
+imgx edit --last -p "Crop to 16:9" -o final.png
+```
+
+### Options
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--prompt` | `-p` | Image description or edit instruction (required) |
+| `--output` | `-o` | Output file path (auto-generated if omitted) |
+| `--input` | `-i` | Input image to edit (`edit` command only) |
+| `--last` | `-l` | Use last output as input (`edit` command only) |
+| `--aspect-ratio` | `-a` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` |
+| `--resolution` | `-r` | `1K`, `2K`, `4K` |
+| `--count` | `-n` | Number of images to generate |
+| `--model` | `-m` | Model name |
+| `--provider` | | Provider name (default: `gemini`) |
+| `--output-dir` | `-d` | Output directory |
+
+### Configuration
+
+```bash
+imgx config set api-key <key>     # Save Gemini API key
+imgx config set model <name>      # Set default model
+imgx config set output-dir <dir>  # Set default output directory
+imgx config set aspect-ratio 16:9 # Set default aspect ratio
+imgx config set resolution 2K     # Set default resolution
+imgx config list                  # Show all settings
+imgx config get api-key           # Show a specific setting (API key is masked)
+imgx config path                  # Show config file location
+```
+
+### Project config (`.imgxrc`)
+
+Generate a template with `imgx init`:
+
+```bash
+imgx init
+# → creates .imgxrc in current directory
+```
+
+Or create manually. Place a `.imgxrc` file in your project directory to set project-level defaults:
+
+```json
+{
+  "defaults": {
+    "model": "gemini-2.5-flash-image",
+    "outputDir": "./assets/images",
+    "aspectRatio": "16:9"
+  }
+}
+```
+
+Project config is shared via Git. Do not put API keys in `.imgxrc` — use `imgx config set api-key` or environment variables instead.
+
+### Settings resolution
+
+Settings are resolved in this order (first match wins):
+
+1. CLI flags (`--model`, `--output-dir`, etc.)
+2. Environment variables (`IMGX_MODEL`, `IMGX_OUTPUT_DIR`, etc.)
+3. Project config (`.imgxrc` in current directory)
+4. User config (`~/.config/imgx/config.json` or `%APPDATA%\imgx\config.json`)
+5. Provider defaults
+
+### Other commands
+
+```bash
+imgx providers      # List available providers and their capabilities
+imgx capabilities   # Show detailed capabilities of current provider
+```
+
+### Environment variables
+
+Environment variables override config file settings.
+
+| Variable | Description |
+|----------|-------------|
+| `GEMINI_API_KEY` | Gemini API key (overrides `imgx config set api-key`) |
+| `IMGX_PROVIDER` | Default provider |
+| `IMGX_MODEL` | Default model |
+| `IMGX_OUTPUT_DIR` | Default output directory |
+
+## Output
+
+All commands output JSON:
+
+```json
+{"success": true, "filePaths": ["./output.png"]}
+```
+
+```json
+{"success": false, "error": "error message"}
+```
+
+This makes imgx suitable for scripting, CI pipelines, and integration with other tools.
+
+## MCP server
+
+imgx includes an MCP (Model Context Protocol) server, making it available to any MCP-compatible AI coding tool.
+
+### Exposed tools
+
+| Tool | Description |
+|------|-------------|
+| `generate_image` | Generate an image from a text prompt |
+| `edit_image` | Edit an existing image with text instructions |
+| `edit_last` | Edit the last generated/edited image (no input path needed) |
+| `list_providers` | List available providers and capabilities |
+
+### Configuration
+
+Add to your tool's MCP config. The `env` section is optional if you have already run `imgx config set api-key`.
+
+**Claude Code** (`.mcp.json` / `claude mcp add`):
+
+```json
+{
+  "mcpServers": {
+    "imgx": {
+      "command": "node",
+      "args": ["/path/to/imgx-cli/dist/mcp.bundle.js"],
+      "env": { "GEMINI_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+**Gemini CLI** (`~/.gemini/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "imgx": {
+      "command": "node",
+      "args": ["/path/to/imgx-cli/dist/mcp.bundle.js"],
+      "env": { "GEMINI_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+**Codex CLI** (`.codex/config.toml`):
+
+```toml
+[mcp_servers.imgx]
+command = "node"
+args = ["/path/to/imgx-cli/dist/mcp.bundle.js"]
+env = { GEMINI_API_KEY = "your-api-key" }
+```
+
+The same configuration pattern works with Cursor, Windsurf, Continue.dev, Cline, Zed, and other MCP-compatible tools.
+
+## Architecture
+
+imgx separates **model-independent** and **model-dependent** concerns:
+
+```
+CLI (argument parsing, output formatting)    MCP server (tool definitions, stdio transport)
+ ↓                                            ↓
+Core (Capability enum, ImageProvider interface, provider registry, file I/O)
+ ↓
+Provider (model-specific API calls, capability declarations)
+```
+
+CLI and MCP server are two entry points into the same core. Both call the same provider functions.
+
+Each provider declares its supported capabilities. The CLI dynamically enables or disables options based on what the active provider supports. Adding a new provider means implementing the `ImageProvider` interface and registering it — no changes to the CLI layer.
+
+### Supported capabilities
+
+| Capability | Description |
+|------------|-------------|
+| `TEXT_TO_IMAGE` | Generate images from text prompts |
+| `IMAGE_EDITING` | Edit images with text instructions |
+| `ASPECT_RATIO` | Control output aspect ratio |
+| `RESOLUTION_CONTROL` | Control output resolution |
+| `MULTIPLE_OUTPUTS` | Generate multiple images per request |
+| `REFERENCE_IMAGES` | Use reference images for guidance |
+| `PERSON_CONTROL` | Control person generation in output |
+
+### Current providers
+
+| Provider | Models | Capabilities |
+|----------|--------|-------------|
+| Gemini | `gemini-3-pro-image-preview`, `gemini-2.5-flash-image` | All 7 capabilities |
+
+## Plugin structure
+
+imgx-cli doubles as an AI coding tool plugin. The repository contains:
+
+```
+.claude-plugin/
+├── plugin.json          # Claude Code plugin manifest
+└── marketplace.json     # Marketplace definition for plugin discovery
+.cursor-plugin/
+└── plugin.json          # Cursor plugin manifest
+.mcp.json                # MCP server config (auto-registered on plugin install)
+skills/
+└── image-generation/
+    ├── SKILL.md         # Skill instructions
+    └── references/
+        └── providers.md # Provider and model reference
+dist/
+├── cli.bundle.js        # Bundled CLI (tracked in git for plugin distribution)
+└── mcp.bundle.js        # Bundled MCP server
+```
+
+When installed as a plugin, the tool clones this repository and registers the skill. The skill instructs the AI to execute `dist/cli.bundle.js` via bash when image generation or editing is requested.
+
+### Plugin configuration files
+
+**`.claude-plugin/plugin.json`** — Plugin identity. Fields: `name`, `description`, `version`, `author`. No `category` field (that belongs in `marketplace.json` only).
+
+**`.claude-plugin/marketplace.json`** — Marketplace wrapper. The `source` field must use URL format for self-referencing repositories:
+
+```json
+"source": {
+  "source": "url",
+  "url": "https://github.com/somacoffeekyoto/imgx-cli.git"
+}
+```
+
+**`skills/image-generation/SKILL.md`** — Uses `${CLAUDE_PLUGIN_ROOT}` variable for portable CLI paths. Frontmatter (`name`, `description`) is required for skill registration.
+
+### Version updates
+
+When releasing a new version, update the version string in all locations:
+
+1. `package.json` — npm package version
+2. `src/cli/index.ts` — CLI `--version` output
+3. `.claude-plugin/plugin.json` — Claude Code plugin manifest version
+4. `.claude-plugin/marketplace.json` — Marketplace plugin entry version
+5. `.cursor-plugin/plugin.json` — Cursor plugin manifest version
+
+Then rebuild (`npm run bundle`) and commit `dist/cli.bundle.js` since plugin distribution relies on the git repository.
+
+## Development
+
+```bash
+git clone https://github.com/somacoffeekyoto/imgx-cli.git
+cd imgx-cli
+npm install
+npm run bundle    # TypeScript compile + esbuild bundle
+```
+
+The build produces two bundles:
+
+- `dist/cli.bundle.js` — CLI entry point
+- `dist/mcp.bundle.js` — MCP server entry point
+
+## Uninstall
+
+### Claude Code plugin
+
+```
+/plugin uninstall imgx-cli@somacoffeekyoto-imgx-cli
+/plugin marketplace remove somacoffeekyoto-imgx-cli
+```
+
+### Standalone CLI
+
+```bash
+npm uninstall -g imgx-cli
+```
+
+### MCP server
+
+Remove the `imgx` entry from your tool's MCP configuration file.
+
+### Clean up configuration (optional)
+
+```bash
+# Linux / macOS
+rm -rf ~/.config/imgx/
+
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$env:APPDATA\imgx"
+```
+
+## License
+
+MIT — [SOMA COFFEE KYOTO](https://github.com/somacoffeekyoto)
+
+## Links
+
+- [GitHub](https://github.com/somacoffeekyoto/imgx-cli)
+- [SOMA COFFEE KYOTO](https://somacoffee.net)
+- [X (@somacoffeekyoto)](https://x.com/somacoffeekyoto)