pixellab-forge-mcp 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rabbitcannon
+
+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,278 @@
+# PixelLab Forge MCP
+
+An MCP server that connects AI assistants to the [PixelLab](https://pixellab.ai) pixel art generation API. Generate sprites, tilesets, characters, animations, and more directly from Claude, Cursor, or any MCP-compatible client.
+
+Generated images are automatically saved to `./pixellab-forge-output/` in your project directory, ready to be moved into your game assets.
+
+## Prerequisites
+
+- **Node.js** 18 or later
+- A **PixelLab API key** — get one at [pixellab.ai/account](https://pixellab.ai/account)
+
+## Setup
+
+No installation needed. `npx` downloads and runs the package automatically on first use.
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add pixellab-forge-mcp -e PIXELLAB_API_KEY=your-api-key-here -- npx pixellab-forge-mcp
+```
+
+This adds it to the current project. To make it available across all your projects:
+
+```bash
+claude mcp add pixellab-forge-mcp -s user -e PIXELLAB_API_KEY=your-api-key-here -- npx pixellab-forge-mcp
+```
+
+That's it. Claude Code will start the server automatically when you begin a conversation.
+
+### Claude Desktop
+
+Add to your config file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "pixellab-forge-mcp": {
+      "command": "npx",
+      "args": ["pixellab-forge-mcp"],
+      "env": {
+        "PIXELLAB_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "pixellab-forge-mcp": {
+      "command": "npx",
+      "args": ["pixellab-forge-mcp"],
+      "env": {
+        "PIXELLAB_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+Any MCP client that supports stdio transport can use PixelLab Forge. Set the command to `npx pixellab-forge-mcp` and pass `PIXELLAB_API_KEY` as an environment variable.
+
+## Generated Images
+
+When a tool returns image data, PixelLab Forge automatically saves the images as PNGs to `./pixellab-forge-output/` in whatever directory the MCP server is running from (usually your project root).
+
+Add this to your `.gitignore`:
+
+```
+pixellab-forge-output/
+```
+
+## Available Tools (47)
+
+Generation tools automatically poll for results — no manual job status checking needed. If a job takes longer than 10 minutes or the connection drops, use `list_pending_jobs` to find the job ID and `get_job_status` to retrieve the result.
+
+### Image Generation
+
+| Tool | Description | Key Options |
+|------|-------------|-------------|
+| `generate_image` | Generate pixel art from text | `reference_images`, `style_image`, `style_options`, `no_background`, `seed` |
+| `generate_with_style` | Match style from 1-4 references | `style_images`, `style_description`, `no_background`, `seed` |
+| `generate_ui` | Game UI elements (buttons, panels, icons) | `concept_image`, `color_palette`, `no_background`, `seed` |
+| `create_image_pixflux` | Pixflux engine (32-400px) | `text_guidance_scale`, `init_image`, `color_image`, `no_background`, `isometric`, `outline/shading/detail`, `seed` |
+| `create_image_bitforge` | Bitforge engine (max 200px) | `text_guidance_scale`, `style_image`, `inpainting_image`, `mask_image`, `color_image`, `skeleton_keypoints`, `outline/shading/detail`, `seed` |
+
+### Characters & Objects
+
+| Tool | Description | Key Options |
+|------|-------------|-------------|
+| `create_character_4dir` | Character with N/S/E/W views | `proportions`, `view`, `text_guidance_scale`, `outline/shading/detail`, `color_image`, `force_colors`, `template_id`, `isometric`, `seed` |
+| `create_character_8dir` | Character with 8 directional views | Same as 4dir |
+| `animate_character` | Animate existing character | `template_animation_id` (walking, fireball, breathing-idle, etc. — [47 templates](docs/prompting-guide.md#animation-templates)), `action_description`, `directions`, `outline/shading/detail`, `seed` |
+| `create_object_4dir` | Object with 4 directional views | `view`, `text_guidance_scale`, `outline/shading/detail`, `color_image`, `force_colors`, `seed` |
+| `list_characters` / `list_objects` | List with pagination | `limit`, `offset` |
+| `get_character` / `get_object` | Get details by ID | |
+| `delete_character` / `delete_object` | Delete by ID | |
+| `download_character_zip` | Export character as ZIP | |
+| `update_character_tags` / `update_object_tags` | Manage tags | |
+
+### Animation
+
+| Tool | Description | Key Options |
+|------|-------------|-------------|
+| `animate_with_text` | Animate from text + reference | `text_guidance_scale`, `image_guidance_scale`, `n_frames`, `init_images`, `color_image`, `seed` |
+| `animate_with_text_v2` | Animate existing image (32-256px) | `reference_image`, `action`, `view`, `direction`, `no_background`, `seed` |
+| `animate_with_text_v3` | Animate from first/last keyframes | `first_frame`, `last_frame`, `frame_count`, `no_background`, `seed` |
+| `animate_with_skeleton` | Pose control via keypoints | `skeleton_keypoints`, `reference_guidance_scale`, `pose_guidance_scale`, `isometric`, `color_image`, `seed` |
+| `edit_animation` | Edit animation frames (2-16) | `frames`, `description`, `no_background`, `seed` |
+| `interpolate_frames` | Generate in-between frames | `start_image`, `end_image`, `action`, `no_background`, `seed` |
+| `transfer_outfit` | Apply outfit to frames | `reference_image`, `frames`, `no_background`, `seed` |
+| `estimate_skeleton` | Extract keypoints from image | `image`, `image_size` |
+
+### Rotation
+
+| Tool | Description | Key Options |
+|------|-------------|-------------|
+| `generate_8_rotations` | 8 directional views (32-168px) | `method` (rotate/style/concept), `view`, `style_description`, `no_background`, `seed` |
+| `rotate` | Rotate between views/directions | `from_view/to_view`, `from_direction/to_direction`, `view_change`, `direction_change`, `image_guidance_scale`, `isometric`, `seed` |
+
+### Editing & Inpainting
+
+| Tool | Description | Key Options |
+|------|-------------|-------------|
+| `edit_images` | Batch edit 1-16 images | `method` (text/reference), `description`, `reference_image`, `no_background`, `seed` |
+| `edit_image` | Edit single image | `image`, `description`, `width`, `height`, `text_guidance_scale`, `color_image`, `no_background`, `seed` |
+| `inpaint_v3` | Mask-based editing | `mask_image`, `bounding_box`, `crop_to_mask`, `no_background`, `seed` |
+| `inpaint` | Inpainting (legacy, max 200px) | `mask_image`, `text_guidance_scale`, `outline/shading/detail`, `isometric`, `color_image`, `seed` |
+
+### Image Operations
+
+| Tool | Description | Key Options |
+|------|-------------|-------------|
+| `image_to_pixelart` | Convert photo to pixel art | `image`, `output_size` |
+| `resize_image` | AI-powered pixel art resize | `reference_image`, `target_size`, `color_image` |
+| `remove_background` | Remove background (max 400px) | `background_removal_task`, `text_hint` |
+
+### Tilesets
+
+| Tool | Description | Key Options |
+|------|-------------|-------------|
+| `create_tileset` | Top-down tileset (16 or 32px) | `lower/upper/transition_description`, `tile_size`, `view`, `text_guidance_scale`, `tile_strength`, `tileset_adherence`, `lower/upper/transition_reference_image`, `seed` |
+| `create_tileset_sidescroller` | Platformer tileset | `lower_description`, `transition_description`, `text_guidance_scale`, `tile_strength`, `tileset_adherence`, `base_tile_id`, `seed` |
+| `create_isometric_tile` | Isometric tile (16-64px) | `isometric_tile_shape` (block/thick/thin), `text_guidance_scale`, `outline/shading/detail`, `color_image`, `seed` |
+| `create_tiles_pro` | Pro tiles (hex, iso, octagon, square) | `tile_type`, `tile_size`, `tile_view`, `tile_depth_ratio`, `style_images`, `style_options`, `n_tiles`, `seed` |
+| `get_tileset` / `get_isometric_tile` / `get_tiles_pro` | Retrieve by ID | |
+
+### Map Objects
+
+| Tool | Description | Key Options |
+|------|-------------|-------------|
+| `create_map_object` | Game-ready object | `view`, `outline/shading/detail`, `text_guidance_scale`, `background_image`, `inpainting`, `color_image`, `seed` |
+
+### Account & Jobs
+
+| Tool | Description |
+|------|-------------|
+| `get_balance` | Check your credit balance |
+| `get_job_status` | Check a background job by ID |
+| `list_pending_jobs` | List jobs that haven't completed (for recovery after disconnection) |
+| `list_job_history` | Recent job history (auto-pruned after 24h) |
+
+### Common Options
+
+Most tools share these parameters, but the field names differ between endpoint generations:
+
+| Concept | v2 endpoints | Legacy endpoints |
+|---------|-------------|------------------|
+| Prompt adherence | n/a | `text_guidance_scale` (1-20) |
+| Transparent background | `no_background` | `no_background` |
+| Color reference | n/a | `color_image` (reference image) |
+| Style controls | n/a | `outline`, `shading`, `detail` |
+| Negative prompt | n/a | `negative_description` |
+| Isometric mode | n/a | `isometric`, `oblique_projection` |
+| Reproducibility | `seed` | `seed` |
+
+Character, object, tileset, and map object endpoints also accept `text_guidance_scale`, `outline`, `shading`, `detail`, and `color_image`.
+
+## Usage
+
+Just describe what you want in plain language. The assistant picks the right tool and parameters automatically.
+
+### Quick Examples
+
+**Sprites and icons:**
+```
+"Generate a 64x64 pixel art knight with a blue cape, no background"
+"Make a 16x16 health potion icon"
+"Create a 128x128 dragon boss with detailed shading and thick outlines"
+```
+
+**Characters (persistent, multi-directional):**
+```
+"Create a 48x48 character with 4 directions: a dwarf blacksmith in a leather apron, chibi proportions"
+"Animate that character with the walk template"
+"Now add a fireball animation"
+```
+
+**Tilesets:**
+```
+"Create a 32x32 top-down tileset: ocean water below, sandy beach on top, foam transition"
+"Make a 16x16 sidescroller tileset with stone platforms"
+```
+
+**Editing existing art:**
+```
+"Edit this sprite to make the armor gold instead of silver"
+"Remove the background from this image"
+"Generate 8 rotations of this character"
+```
+
+### Which Tool Gets Used?
+
+The assistant picks the right tool automatically, but the key decision is:
+
+- **`generate_image`** — default for most requests, highest quality, largest sizes
+- **`generate_with_style`** — when you want new art matching existing art ("in the same style as these sprites")
+- **`generate_ui`** — for game UI elements (buttons, panels, health bars, icons)
+- **`create_tileset` / `create_tiles_pro`** — for tileable terrain; standard for square RPG tiles, pro for hex/isometric/octagon
+- **`create_character_4dir` / `8dir`** — for persistent characters you can animate later by ID
+
+### Key Concepts
+
+- **Sizes are in pixels** as `width x height` — different tools have different limits (e.g. characters max 128x128, `generate_image` goes up to 792x688)
+- **Transparent backgrounds** are the default on most tools — ask for a background explicitly if you want one
+- **Characters are persistent** — once created, you can animate them by ID without re-describing
+- **Seeds** make results reproducible — same seed + same description = same output
+
+For detailed size limits, style controls, endpoint comparison, and step-by-step workflows, see the **[Prompting Guide](docs/prompting-guide.md)**.
+
+### Prompt Commands
+
+PixelLab Forge includes MCP prompt templates that appear as slash commands in supported clients (Claude Desktop, Cursor, etc.):
+
+| Command | Description |
+|---------|-------------|
+| `pf:help` | Overview of all tools and how to use them |
+| `pf:sprite` | Generate a pixel art sprite |
+| `pf:character` | Create a character with directional views + animation |
+| `pf:animate` | Animate an existing sprite or character |
+| `pf:tileset` | Create a top-down or sidescroller tileset |
+| `pf:tiles` | Create hex, isometric, or octagon tiles |
+| `pf:ui` | Generate game UI elements |
+| `pf:style` | Generate art matching existing sprites' style |
+| `pf:edit` | Edit or modify an existing sprite |
+
+## Reliability
+
+- **Auto-polling**: Generation jobs are polled every 2 seconds for up to 10 minutes
+- **Retry on failure**: Network errors during polling are retried 3 times with backoff
+- **Job recovery**: If the connection drops, job IDs are logged to stderr and persisted to disk. Use `list_pending_jobs` to find them and `get_job_status` to retrieve results
+- **Image saving**: Generated images are automatically saved as PNGs to `./pixellab-forge-output/`
+
+## Testing
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+Set `PIXELLAB_API_KEY` in the inspector's environment variables, connect, and test any tool.
+
+## Contributing
+
+Contributions are welcome via pull requests.
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,9 @@
+export declare class PixelLabClient {
+    private apiKey;
+    constructor(apiKey: string);
+    private headers;
+    get(path: string): Promise<unknown>;
+    delete(path: string): Promise<unknown>;
+    patch(path: string, body: unknown): Promise<unknown>;
+    post(path: string, body: unknown): Promise<unknown>;
+}

package/dist/api-client.js

@@ -0,0 +1,89 @@
+import { logJobStart } from "./job-log.js";
+const BASE_URL = "https://api.pixellab.ai/v2";
+function debugLog(msg) {
+    process.stderr.write(`[pixellab-forge-mcp] ${msg}\n`);
+}
+export class PixelLabClient {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    headers(contentType = "application/json") {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": contentType,
+        };
+    }
+    async get(path) {
+        const res = await fetch(`${BASE_URL}${path}`, {
+            method: "GET",
+            headers: this.headers(),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`GET ${path} failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async delete(path) {
+        const res = await fetch(`${BASE_URL}${path}`, {
+            method: "DELETE",
+            headers: this.headers(),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`DELETE ${path} failed (${res.status}): ${text}`);
+        }
+        if (res.status === 204)
+            return { success: true };
+        return res.json();
+    }
+    async patch(path, body) {
+        const res = await fetch(`${BASE_URL}${path}`, {
+            method: "PATCH",
+            headers: this.headers(),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`PATCH ${path} failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async post(path, body) {
+        const jsonBody = JSON.stringify(body);
+        debugLog(`POST ${path} — payload size: ${jsonBody.length} bytes`);
+        // Extract description for job logging
+        const desc = body && typeof body === "object"
+            ? body.description
+                ?? body.text
+            : undefined;
+        const res = await fetch(`${BASE_URL}${path}`, {
+            method: "POST",
+            headers: this.headers(),
+            body: jsonBody,
+        });
+        debugLog(`POST ${path} — response status: ${res.status}`);
+        if (res.status === 200) {
+            return res.json();
+        }
+        if (res.status === 202) {
+            const data = (await res.json());
+            const jobId = data.job_id ?? data.background_job_id;
+            debugLog(`POST ${path} — background job: ${jobId}`);
+            if (jobId) {
+                logJobStart(jobId, path, desc);
+            }
+            return {
+                status: "processing",
+                job_id: jobId,
+                endpoint: path,
+                message: `Job ${jobId} is processing. Use get_job_status with this job_id to check progress and retrieve results.`,
+            };
+        }
+        const text = await res.text();
+        debugLog(`POST ${path} — ERROR ${res.status}: ${text}`);
+        throw new Error(`POST ${path} failed (${res.status}): ${text}`);
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { PixelLabClient } from "./api-client.js";
+import { tools } from "./tools.js";
+import { prompts } from "./prompts.js";
+import { extractAndSaveImages } from "./save-images.js";
+import { getJobEndpoint, getJobDescription } from "./job-log.js";
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_|_$/g, "")
+        .slice(0, 60);
+}
+const apiKey = process.env["PIXELLAB_API_KEY"];
+if (!apiKey) {
+    console.error("Error: PIXELLAB_API_KEY environment variable is required.");
+    console.error("Get your API key from https://pixellab.ai/account");
+    process.exit(1);
+}
+const client = new PixelLabClient(apiKey);
+const server = new Server({ name: "pixellab-forge-mcp", version: "1.2.0" }, { capabilities: { tools: {}, prompts: {} } });
+const toolMap = new Map(tools.map((t) => [t.name, t]));
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name } = request.params;
+    const args = request.params.arguments ?? {};
+    const tool = toolMap.get(name);
+    if (!tool) {
+        return {
+            content: [{ type: "text", text: `Unknown tool: ${name}` }],
+            isError: true,
+        };
+    }
+    try {
+        const result = await tool.handler(client, args);
+        process.stderr.write(`[pixellab-forge-mcp] Raw response keys for ${name}: ${result && typeof result === "object" ? JSON.stringify(Object.keys(result)) : typeof result}\n`);
+        // read_image returns raw base64 for use in subsequent tool calls — skip extraction/stripping
+        if (name === "read_image") {
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        // Derive a meaningful filename from the prompt description when available
+        let imageLabel = name;
+        const desc = args.description ?? args.text;
+        if (typeof desc === "string" && desc.length > 0) {
+            imageLabel = slugify(desc);
+        }
+        else if (name === "get_job_status" && typeof args.job_id === "string") {
+            // Look up the original description stored when the job was created
+            const jobDesc = getJobDescription(args.job_id);
+            if (jobDesc) {
+                imageLabel = slugify(jobDesc);
+            }
+            else {
+                const endpoint = getJobEndpoint(args.job_id);
+                if (endpoint) {
+                    imageLabel = endpoint.replace(/^\//, "").replace(/-/g, "_");
+                }
+            }
+        }
+        const { images, result: strippedResult } = extractAndSaveImages(result, imageLabel);
+        process.stderr.write(`[pixellab-forge-mcp] Extracted ${images.length} image(s), valid for inline: ${images.filter(i => i.base64.length > 0).length}\n`);
+        if (images.length > 0) {
+            const first = images[0];
+            process.stderr.write(`[pixellab-forge-mcp] First image: base64 length=${first.base64.length}, mime=${first.mimeType}, path=${first.filePath}\n`);
+        }
+        const parts = [];
+        if (images.length > 0) {
+            // Limit inline image blocks to avoid overwhelming the Claude API.
+            // All images are still saved to disk regardless.
+            const MAX_INLINE_IMAGES = 4;
+            const inlineImages = images.slice(0, MAX_INLINE_IMAGES);
+            parts.push({
+                type: "text",
+                text: `Saved ${images.length} image(s):\n${images.map((img) => img.filePath).join("\n")}${images.length > MAX_INLINE_IMAGES
+                    ? `\n\n(Showing first ${MAX_INLINE_IMAGES} of ${images.length} images inline. All images saved to disk.)`
+                    : ""}`,
+            });
+            for (const img of inlineImages) {
+                if (img.base64) {
+                    parts.push({
+                        type: "image",
+                        data: img.base64,
+                        mimeType: img.mimeType,
+                    });
+                }
+            }
+        }
+        parts.push({
+            type: "text",
+            text: JSON.stringify(strippedResult, null, 2),
+        });
+        return { content: parts };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+const promptMap = new Map(prompts.map((p) => [p.name, p]));
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: prompts.map((p) => ({
+        name: p.name,
+        description: p.description,
+        arguments: p.arguments,
+    })),
+}));
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name } = request.params;
+    const args = request.params.arguments ?? {};
+    const prompt = promptMap.get(name);
+    if (!prompt) {
+        throw new Error(`Unknown prompt: ${name}`);
+    }
+    return {
+        description: prompt.description,
+        messages: prompt.messages(args),
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/job-log.d.ts

@@ -0,0 +1,16 @@
+interface JobEntry {
+    id: string;
+    endpoint: string;
+    description?: string;
+    status: "pending" | "completed" | "failed";
+    created: string;
+    completed?: string;
+}
+export declare function logJobStart(jobId: string, endpoint: string, description?: string): void;
+export declare function logJobComplete(jobId: string): void;
+export declare function logJobFailed(jobId: string): void;
+export declare function getPendingJobs(): JobEntry[];
+export declare function getJobLog(): JobEntry[];
+export declare function getJobEndpoint(jobId: string): string | undefined;
+export declare function getJobDescription(jobId: string): string | undefined;
+export {};

package/dist/job-log.js

@@ -0,0 +1,88 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+const LOG_DIR = join(tmpdir(), "pixellab-forge");
+const LOG_FILE = join(LOG_DIR, "jobs.json");
+const MAX_ENTRIES = 200;
+const TTL_HOURS = 24;
+function ensureDir() {
+    try {
+        mkdirSync(LOG_DIR, { recursive: true });
+    }
+    catch {
+        // already exists
+    }
+}
+function readLog() {
+    try {
+        return JSON.parse(readFileSync(LOG_FILE, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+function writeLog(entries) {
+    ensureDir();
+    writeFileSync(LOG_FILE, JSON.stringify(entries, null, 2));
+}
+/** Remove completed jobs older than TTL and cap total entries */
+function prune(entries) {
+    const cutoff = Date.now() - TTL_HOURS * 60 * 60 * 1000;
+    const pruned = entries.filter((e) => {
+        // Always keep pending jobs (they might still be recoverable)
+        if (e.status === "pending")
+            return true;
+        // Remove completed/failed jobs older than TTL
+        const ts = new Date(e.completed ?? e.created).getTime();
+        return ts > cutoff;
+    });
+    // Cap at MAX_ENTRIES, keeping newest
+    if (pruned.length > MAX_ENTRIES) {
+        return pruned.slice(pruned.length - MAX_ENTRIES);
+    }
+    return pruned;
+}
+export function logJobStart(jobId, endpoint, description) {
+    const entries = prune(readLog());
+    entries.push({
+        id: jobId,
+        endpoint,
+        description,
+        status: "pending",
+        created: new Date().toISOString(),
+    });
+    writeLog(entries);
+}
+export function logJobComplete(jobId) {
+    const entries = readLog();
+    const entry = entries.find((e) => e.id === jobId);
+    if (entry) {
+        entry.status = "completed";
+        entry.completed = new Date().toISOString();
+        writeLog(prune(entries));
+    }
+}
+export function logJobFailed(jobId) {
+    const entries = readLog();
+    const entry = entries.find((e) => e.id === jobId);
+    if (entry) {
+        entry.status = "failed";
+        entry.completed = new Date().toISOString();
+        writeLog(prune(entries));
+    }
+}
+export function getPendingJobs() {
+    return readLog().filter((e) => e.status === "pending");
+}
+export function getJobLog() {
+    return prune(readLog());
+}
+export function getJobEndpoint(jobId) {
+    const entry = readLog().find((e) => e.id === jobId);
+    return entry?.endpoint;
+}
+export function getJobDescription(jobId) {
+    const entry = readLog().find((e) => e.id === jobId);
+    return entry?.description;
+}
+//# sourceMappingURL=job-log.js.map