restyle-sprites 0.1.0

package/dist/cli.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { config as loadEnv } from 'dotenv';
+import inquirer from 'inquirer';
+import { AssetPackWriter } from './AssetPackWriter.js';
+import { BatchGenerator } from './BatchGenerator.js';
+import { loadConfig } from './config.js';
+import { ImageProcessor } from './ImageProcessor.js';
+import { OpenAIImageClient } from './OpenAIImageClient.js';
+import { PixelArtPostProcessor } from './PixelArtPostProcessor.js';
+import { StyleExplorer } from './StyleExplorer.js';
+function readArg(name) {
+    const args = process.argv.slice(2);
+    const direct = args.find((arg) => arg.startsWith(`--${name}=`));
+    if (direct) {
+        return direct.slice(name.length + 3);
+    }
+    const index = args.indexOf(`--${name}`);
+    if (index >= 0 && args[index + 1]) {
+        return args[index + 1];
+    }
+    return undefined;
+}
+function requireArg(name) {
+    const value = readArg(name)?.trim();
+    if (!value) {
+        throw new Error(`Missing required argument --${name}`);
+    }
+    return value;
+}
+function loadLocalEnvironment(configDir) {
+    const envPath = path.join(configDir, '.env');
+    loadEnv({ path: envPath, quiet: true });
+}
+async function resolvePackName() {
+    const fromArg = readArg('name');
+    if (fromArg && fromArg.trim().length > 0) {
+        return fromArg.trim();
+    }
+    const answer = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'packName',
+            message: 'Asset pack name',
+            validate: (value) => (value.trim().length > 0 ? true : 'Pack name is required.'),
+        },
+    ]);
+    return answer.packName.trim();
+}
+async function ensurePackDirectories(outputRootDir, packName) {
+    const packDir = path.join(outputRootDir, packName);
+    const spritesDir = path.join(packDir, 'sprites');
+    await fs.mkdir(spritesDir, { recursive: true });
+    return { packDir, spritesDir };
+}
+async function exploreStyle(packName, workspaceRoot, outputRootDir, sampleSprites) {
+    const { packDir } = await ensurePackDirectories(outputRootDir, packName);
+    const imageProcessor = new ImageProcessor();
+    const styleExplorer = new StyleExplorer(new OpenAIImageClient(), {
+        workspaceRoot,
+        sampleSprites,
+        imageProcessor,
+    });
+    const result = await styleExplorer.runInteractive(packDir);
+    const writer = new AssetPackWriter();
+    await writer.writeManifest({
+        packDir,
+        packName,
+        description: `Style exploration draft for ${packName}. Style prompt: ${result.prompt}`,
+        styleReferenceImage: path.basename(result.styleReferencePath),
+        assets: [],
+    });
+    await writer.updatePackIndex({ packsRootDir: outputRootDir, activePack: 'default' });
+    console.log(`Style reference stored at ${result.styleReferencePath}`);
+}
+async function exploreStyleOnce(packName, styleDirection, workspaceRoot, outputRootDir, sampleSprites) {
+    const { packDir } = await ensurePackDirectories(outputRootDir, packName);
+    const client = new OpenAIImageClient();
+    const imageProcessor = new ImageProcessor();
+    const sampleSheet = await StyleExplorer.buildSampleSheetFromSources(workspaceRoot, imageProcessor, sampleSprites);
+    const sampleSheetPath = path.join(packDir, 'style-source-sample.png');
+    await fs.writeFile(sampleSheetPath, sampleSheet);
+    const stylePrompt = StyleExplorer.buildStyleReferencePrompt(styleDirection);
+    const styleResult = await client.generateStyleReference(stylePrompt, sampleSheetPath);
+    const writer = new AssetPackWriter();
+    const styleReferencePath = path.join(packDir, 'style-reference.png');
+    await fs.writeFile(styleReferencePath, styleResult.image);
+    await writer.writeManifest({
+        packDir,
+        packName,
+        description: `Style exploration draft for ${packName}. Style direction: ${styleDirection}`,
+        styleReferenceImage: path.basename(styleReferencePath),
+        assets: [],
+    });
+    await writer.updatePackIndex({ packsRootDir: outputRootDir, activePack: 'default' });
+    console.log(`Style reference stored at ${styleReferencePath}`);
+}
+async function readStylePromptFromManifest(packDir) {
+    const manifestPath = path.join(packDir, 'manifest.json');
+    try {
+        const raw = await fs.readFile(manifestPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.description) {
+            return null;
+        }
+        const match = parsed.description.match(/Style (?:direction|prompt):\s*(.+)$/i);
+        return match?.[1]?.trim() ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function generatePack(params) {
+    const { packDir } = await ensurePackDirectories(params.outputRootDir, params.packName);
+    const styleReferencePath = path.join(packDir, 'style-reference.png');
+    await fs.access(styleReferencePath);
+    const styleDirectionFromManifest = await readStylePromptFromManifest(packDir);
+    const styleDirection = params.stylePromptArg?.trim() ??
+        styleDirectionFromManifest ??
+        'Stylized 2D game sprites, cohesive palette, clean edges, high contrast, tiny-sprite readability';
+    const batchGenerator = new BatchGenerator(new OpenAIImageClient(), new ImageProcessor(), new PixelArtPostProcessor());
+    const assets = await batchGenerator.generatePackAssets({
+        workspaceRoot: params.workspaceRoot,
+        assets: params.assets,
+        styleReferencePath,
+        outputPackDir: packDir,
+        stylePrompt: styleDirection,
+    });
+    const writer = new AssetPackWriter();
+    await writer.writeManifest({
+        packDir,
+        packName: params.packName,
+        description: `AI restyled asset pack: ${params.packName}`,
+        styleReferenceImage: 'style-reference.png',
+        assets,
+    });
+    await writer.updatePackIndex({ packsRootDir: params.outputRootDir, activePack: params.packName });
+    console.log(`Asset pack generated: ${packDir}`);
+}
+async function initDefaultPack(workspaceRoot, outputRootDir, assetsConfig) {
+    const imageProcessor = new ImageProcessor();
+    const { packDir } = await ensurePackDirectories(outputRootDir, 'default');
+    const assets = [];
+    for (const asset of assetsConfig) {
+        const sourcePath = path.join(workspaceRoot, asset.sourceFile);
+        const outputPath = path.join(packDir, asset.outputFile);
+        await imageProcessor.convertToPng(sourcePath, outputPath);
+        assets.push({
+            id: asset.id,
+            metadata: asset.metadata,
+            file: asset.outputFile,
+            kind: asset.kind,
+            width: asset.width,
+            height: asset.height,
+            frameWidth: asset.kind === 'spritesheet' ? asset.frameWidth : undefined,
+            frameHeight: asset.kind === 'spritesheet' ? asset.frameHeight : undefined,
+            frameCount: asset.kind === 'spritesheet' ? asset.frameCount : undefined,
+            frameDirection: asset.kind === 'spritesheet' ? asset.frameDirection : undefined,
+        });
+    }
+    const writer = new AssetPackWriter();
+    await writer.writeManifest({
+        packDir,
+        packName: 'default',
+        description: 'Baseline asset pack converted from source assets',
+        assets,
+    });
+    await writer.updatePackIndex({ packsRootDir: outputRootDir, activePack: 'default' });
+    console.log('Default asset pack generated.');
+}
+function printHelp() {
+    console.log([
+        'restyle-sprites',
+        '',
+        'Commands:',
+        '  explore       --name <pack> --config <path>',
+        '  explore-once  --name <pack> --config <path> --prompt "<style direction>"',
+        '  generate      --name <pack> --config <path> [--style "<style direction>"]',
+        '  init-default  --config <path>',
+        '',
+        'Notes:',
+        '  - --config supports .json, .yaml, .yml',
+        '  - all source/output paths are resolved relative to the config file directory',
+    ].join('\n'));
+}
+async function main() {
+    const command = process.argv[2];
+    if (!command || command === '--help' || command === '-h' || command === 'help') {
+        printHelp();
+        return;
+    }
+    const configArg = readArg('config') ?? 'restyle.config.json';
+    const { configDir, config } = await loadConfig(configArg);
+    loadLocalEnvironment(configDir);
+    const workspaceRoot = configDir;
+    const outputRootDir = path.resolve(configDir, config.outputDir);
+    await fs.mkdir(outputRootDir, { recursive: true });
+    if (command === 'explore') {
+        const packName = await resolvePackName();
+        await exploreStyle(packName, workspaceRoot, outputRootDir, config.sampleSprites);
+        return;
+    }
+    if (command === 'explore-once') {
+        const packName = await resolvePackName();
+        const styleDirection = requireArg('prompt');
+        await exploreStyleOnce(packName, styleDirection, workspaceRoot, outputRootDir, config.sampleSprites);
+        return;
+    }
+    if (command === 'generate') {
+        const packName = await resolvePackName();
+        await generatePack({
+            packName,
+            workspaceRoot,
+            outputRootDir,
+            stylePromptArg: readArg('style'),
+            assets: config.assets,
+        });
+        return;
+    }
+    if (command === 'init-default') {
+        await initDefaultPack(workspaceRoot, outputRootDir, config.assets);
+        return;
+    }
+    console.error('Unknown command. Use one of: explore, explore-once, generate, init-default');
+    process.exitCode = 1;
+}
+void main();

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+import { RestyleSpritesConfig } from './types.js';
+interface LoadedConfig {
+    configPath: string;
+    configDir: string;
+    config: RestyleSpritesConfig;
+}
+export declare function loadConfig(configPathArg: string): Promise<LoadedConfig>;
+export {};

package/dist/config.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import yaml from 'js-yaml';
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function assertString(value, field) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`Invalid config field "${field}": expected non-empty string.`);
+    }
+    return value.trim();
+}
+function assertNumber(value, field) {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        throw new Error(`Invalid config field "${field}": expected number.`);
+    }
+    return value;
+}
+function parseAssetDefinition(value, index) {
+    if (!isObject(value)) {
+        throw new Error(`Invalid config field "assets[${index}]": expected object.`);
+    }
+    const kind = assertString(value.kind, `assets[${index}].kind`);
+    const base = {
+        id: assertString(value.id, `assets[${index}].id`),
+        sourceFile: assertString(value.sourceFile, `assets[${index}].sourceFile`),
+        outputFile: assertString(value.outputFile, `assets[${index}].outputFile`),
+        kind,
+        category: value.category,
+        width: assertNumber(value.width, `assets[${index}].width`),
+        height: assertNumber(value.height, `assets[${index}].height`),
+        promptHint: assertString(value.promptHint, `assets[${index}].promptHint`),
+        metadata: isObject(value.metadata) ? value.metadata : undefined,
+    };
+    if (kind === 'image') {
+        return {
+            ...base,
+            kind: 'image',
+        };
+    }
+    if (kind === 'spritesheet') {
+        return {
+            ...base,
+            kind: 'spritesheet',
+            frameWidth: assertNumber(value.frameWidth, `assets[${index}].frameWidth`),
+            frameHeight: assertNumber(value.frameHeight, `assets[${index}].frameHeight`),
+            frameCount: assertNumber(value.frameCount, `assets[${index}].frameCount`),
+            frameDirection: assertString(value.frameDirection, `assets[${index}].frameDirection`),
+        };
+    }
+    throw new Error(`Invalid config field "assets[${index}].kind": expected "image" or "spritesheet".`);
+}
+function validateConfig(data) {
+    if (!isObject(data)) {
+        throw new Error('Invalid config: expected object at root.');
+    }
+    const assetsRaw = data.assets;
+    if (!Array.isArray(assetsRaw) || assetsRaw.length === 0) {
+        throw new Error('Invalid config field "assets": expected non-empty array.');
+    }
+    const sampleSpritesRaw = data.sampleSprites;
+    if (!Array.isArray(sampleSpritesRaw) || sampleSpritesRaw.length === 0) {
+        throw new Error('Invalid config field "sampleSprites": expected non-empty array.');
+    }
+    return {
+        outputDir: assertString(data.outputDir, 'outputDir'),
+        assets: assetsRaw.map((asset, index) => parseAssetDefinition(asset, index)),
+        sampleSprites: sampleSpritesRaw.map((sample, index) => assertString(sample, `sampleSprites[${index}]`)),
+        defaultActivePack: typeof data.defaultActivePack === 'string' && data.defaultActivePack.trim().length > 0
+            ? data.defaultActivePack.trim()
+            : undefined,
+    };
+}
+export async function loadConfig(configPathArg) {
+    const configPath = path.resolve(configPathArg);
+    const configDir = path.dirname(configPath);
+    const raw = await fs.readFile(configPath, 'utf8');
+    const ext = path.extname(configPath).toLowerCase();
+    const parsed = ext === '.yaml' || ext === '.yml'
+        ? yaml.load(raw)
+        : ext === '.json'
+            ? JSON.parse(raw)
+            : (() => {
+                throw new Error(`Unsupported config extension "${ext}". Use .json, .yaml, or .yml`);
+            })();
+    return {
+        configPath,
+        configDir,
+        config: validateConfig(parsed),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './config.js';
+export * from './AssetPackWriter.js';
+export * from './BatchGenerator.js';
+export * from './ImageProcessor.js';
+export * from './OpenAIImageClient.js';
+export * from './PixelArtPostProcessor.js';
+export * from './StyleExplorer.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './config.js';
+export * from './AssetPackWriter.js';
+export * from './BatchGenerator.js';
+export * from './ImageProcessor.js';
+export * from './OpenAIImageClient.js';
+export * from './PixelArtPostProcessor.js';
+export * from './StyleExplorer.js';

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+export type AssetKind = 'image' | 'spritesheet';
+export type AssetCategory = 'character' | 'resource' | 'effect' | 'prop' | 'icon' | 'scene' | 'font';
+export interface AssetDefinitionBase {
+    id: string;
+    sourceFile: string;
+    outputFile: string;
+    kind: AssetKind;
+    category?: AssetCategory;
+    width: number;
+    height: number;
+    promptHint: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ImageAssetDefinition extends AssetDefinitionBase {
+    kind: 'image';
+}
+export interface SpriteSheetAssetDefinition extends AssetDefinitionBase {
+    kind: 'spritesheet';
+    frameWidth: number;
+    frameHeight: number;
+    frameCount: number;
+    frameDirection: 'vertical' | 'horizontal';
+}
+export type AssetDefinition = ImageAssetDefinition | SpriteSheetAssetDefinition;
+export interface StyleReference {
+    packName: string;
+    prompt: string;
+    imagePath: string;
+}
+export interface AssetPackManifestEntry {
+    id: string;
+    file: string;
+    kind: AssetKind;
+    width: number;
+    height: number;
+    frameWidth?: number;
+    frameHeight?: number;
+    frameCount?: number;
+    frameDirection?: 'vertical' | 'horizontal';
+    metadata?: Record<string, unknown>;
+}
+export interface AssetPackManifest {
+    name: string;
+    description: string;
+    createdAt: string;
+    styleReferenceImage?: string;
+    assets: AssetPackManifestEntry[];
+}
+export interface RestyleSpritesConfig {
+    outputDir: string;
+    assets: AssetDefinition[];
+    sampleSprites: string[];
+    defaultActivePack?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "restyle-sprites",
+  "version": "0.1.0",
+  "description": "AI-powered sprite restyling pipeline for consistent game asset packs",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lx-0/restyle-sprites.git"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "restyle-sprites": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "dotenv": "^17.3.1",
+    "image-q": "^4.0.0",
+    "inquirer": "^13.3.0",
+    "js-yaml": "^4.1.0",
+    "openai": "^6.25.0",
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.5",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.3.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.2",
+    "vitest": "^2.1.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish"
+  }
+}