@goodandready/dsh-image-gen 0.10.24 → 0.10.26

package/lib/tools/responsive.js

@@ -0,0 +1,267 @@
+// responsive — generate_responsive_mockups tool (#173)
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import {
+  makeProviders,
+  toLosslessJson,
+  saveAttachmentSafe,
+  tryGenerate,
+  fallbackOrder,
+  PROVIDER_KEYS,
+} from '../providers.js'
+import { trackAndAssertLoopGuard } from '../loop-guard.js'
+import { sanitizeErrorAndLogs } from '../security.js'
+import { buildDualOutputMarkdown } from '../resolve-image.js'
+import {
+  buildResponsivePrompt,
+  deviceMeta,
+  mockupFileName,
+  normalizeDevices,
+  resolveDevicePreset,
+} from '../responsive-helpers.js'
+
+async function asyncPool(tasks, concurrency = 3) {
+  const results = new Array(tasks.length)
+  let nextIdx = 0
+  async function worker() {
+    while (nextIdx < tasks.length) {
+      const idx = nextIdx++
+      results[idx] = await tasks[idx]()
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, tasks.length) }, () => worker()),
+  )
+  return results
+}
+
+export function registerResponsiveTools(ctx, deps) {
+  const { live, resolveApiKey } = deps
+
+  ctx.effect(() => {
+    ctx.tools.register(
+      defineTool({
+        name: 'generate_responsive_mockups',
+        description:
+          'Generate one product UI mockup across Mobile (9:16), Tablet (3:4) and Desktop (16:9) viewports in one call (#173). '
+          + 'Keeps prompt, style and brand palette synchronized so the three screens look like the same product family. '
+          + 'Saves mockup-mobile.png, mockup-tablet.png and mockup-desktop.png and shows a tabbed preview in chat.',
+        parameters: {
+          prompt: {
+            type: 'string',
+            required: true,
+            description: 'Shared product/screen description used for all viewports (e.g. "settings dashboard for a smart home app").',
+          },
+          devices: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Subset of viewports: mobile, tablet, desktop. Default: all three.',
+          },
+          style_preset: {
+            type: 'string',
+            description: 'Optional style preset shared by all viewports (same catalog as generate_image).',
+          },
+          palette_colors: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Optional brand color hex list enforced across every viewport for visual consistency.',
+          },
+          seed: {
+            type: 'integer',
+            description: 'Optional base seed for reproducible responsive sets (each device uses seed, seed+1, seed+2…).',
+          },
+          output_name: {
+            type: 'string',
+            description: 'Optional file stem. Default produces mockup-mobile.png, mockup-tablet.png, mockup-desktop.png.',
+          },
+          output_dir: {
+            type: 'string',
+            description: 'Optional directory relative to session cwd (defaults to settings outputDir).',
+          },
+        },
+        output: {
+          schema: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              summary: { type: 'string' },
+              images: { type: 'array', items: { type: 'object', additionalProperties: true } },
+              devices: { type: 'array', items: { type: 'string' } },
+              count: { type: 'number' },
+              seedBase: { type: 'number' },
+              provider: { type: 'string' },
+              warnings: { type: 'array', items: { type: 'string' } },
+            },
+          },
+        },
+        async execute(args, exec) {
+          try {
+            const cfg = live()
+            trackAndAssertLoopGuard(exec?.agent?.session?.id || 'default', { limit: cfg.loopGuardLimit })
+            if (!args.prompt || !String(args.prompt).trim()) {
+              throw new Error('prompt is required for generate_responsive_mockups')
+            }
+
+            const devices = normalizeDevices(args.devices)
+            if (!devices.length) {
+              throw new Error('devices must include at least one of: mobile, tablet, desktop')
+            }
+
+            const provider = cfg.provider || 'fal'
+            const format = cfg.defaultFormat || 'png'
+            const seedBase = Number.isInteger(args.seed) ? args.seed : Math.floor(Math.random() * 100000)
+            const stylePreset = args.style_preset || cfg.stylePreset
+            const paletteColors = Array.isArray(args.palette_colors) ? args.palette_colors : undefined
+            const sessionCwd = exec?.agent?.session?.header?.cwd
+            const targetDir = (args.output_dir && String(args.output_dir).trim()) || cfg.outputDir || 'generated/images'
+            const outDir = path.resolve(sessionCwd || process.cwd(), targetDir)
+            await mkdir(outDir, { recursive: true })
+
+            const pdeps = {
+              fetchImpl: fetch,
+              resolveKey: (ref) => resolveApiKey(ctx, ref),
+              cfg,
+            }
+            const order = fallbackOrder(provider)
+            const warnings = []
+
+            const tasks = devices.map((device, index) => async () => {
+              const preset = resolveDevicePreset(device)
+              const devicePrompt = buildResponsivePrompt(args.prompt, {
+                device,
+                stylePreset,
+                paletteColors,
+              })
+              const seed = seedBase + index
+              const job = {
+                prompt: devicePrompt,
+                size: preset.size,
+                format,
+                seed,
+                provider,
+                ...(stylePreset ? { style: stylePreset, style_preset: stylePreset } : {}),
+                ...(paletteColors ? { palette_colors: paletteColors } : {}),
+              }
+              const providers = makeProviders(pdeps, job)
+              const generators = Object.fromEntries(PROVIDER_KEYS.map((k) => [
+                k,
+                async (s, p) => {
+                  const fn = providers[k]
+                  if (typeof fn !== 'function') throw new Error(`provider ${k} unavailable`)
+                  return fn(s, p)
+                },
+              ]))
+
+              try {
+                const gen = await tryGenerate(generators, order, seed, devicePrompt)
+                let bytes = gen.bytes || gen.image || gen.buffer
+                if (bytes && !Buffer.isBuffer(bytes)) bytes = Buffer.from(bytes)
+                if (!bytes || !bytes.length) throw new Error('provider returned empty image bytes')
+
+                const name = mockupFileName(device, {
+                  outputName: String(args.output_name || '').trim() || undefined,
+                })
+                const mediaType = gen.mediaType
+                  || `image/${String(gen.format || format).replace('jpg', 'jpeg')}`
+                const { attachment, localUrl } = await saveAttachmentSafe(ctx, {
+                  bytes,
+                  mediaType,
+                  name,
+                })
+                const filePath = path.join(outDir, name)
+                await writeFile(filePath, bytes)
+                const meta = deviceMeta(device)
+                return {
+                  success: true,
+                  ...meta,
+                  seed,
+                  path: filePath,
+                  url: localUrl,
+                  width: gen.width || attachment.width,
+                  height: gen.height || attachment.height,
+                  cost: gen.cost || 0,
+                  prompt: devicePrompt,
+                  format: String(gen.format || format).replace('jpg', 'jpeg'),
+                  attachment: {
+                    attachmentId: attachment.attachmentId,
+                    mediaType: attachment.mediaType,
+                    bytes: attachment.bytes,
+                    width: attachment.width,
+                    height: attachment.height,
+                    name: attachment.name,
+                  },
+                }
+              } catch (err) {
+                warnings.push(`${preset.id}: ${err?.message || err}`)
+                return { device: preset.id, success: false, error: err?.message || String(err) }
+              }
+            })
+
+            const settled = await asyncPool(tasks, 3)
+            const images = settled.filter((r) => r && r.success === true)
+            if (!images.length) {
+              throw new Error(`All responsive mockup generations failed: ${warnings.join('; ') || 'unknown error'}`)
+            }
+
+            const first = images[0]
+            const totalCost = images.reduce((s, i) => s + (i.cost || 0), 0)
+            const summaryBody = buildDualOutputMarkdown({
+              action: 'generated',
+              filePath: first.path,
+              width: first.width,
+              height: first.height,
+              mediaType: first.mediaType || `image/${format}`,
+              seed: seedBase,
+              provider,
+              model: cfg.model || cfg.customModel || 'default',
+              cost: totalCost,
+              attachmentId: first.attachment?.attachmentId || 'N/A',
+            })
+            const extraLines = images
+              .map((i) => `- **${i.device}** \`${i.path}\` (${i.width}×${i.height})`)
+              .join('\n')
+            // Machine-readable payload for the toolview tab strip (#173).
+            const tabPayload = JSON.stringify({
+              kind: 'generate_responsive_mockups',
+              images: images.map((i) => ({
+                device: i.device,
+                label: i.label,
+                aspect: i.aspect,
+                width: i.width,
+                height: i.height,
+                path: i.path,
+                seed: i.seed,
+                url: i.url,
+                attachment: i.attachment,
+              })),
+            })
+            const summary = `${summaryBody}\n\n**Responsive set (${images.length} viewports)**\n${extraLines}\n\n<dsh-image-gen-responsive>${tabPayload}</dsh-image-gen-responsive>`
+
+            return toLosslessJson({
+              summary,
+              images,
+              devices: images.map((i) => i.device),
+              count: images.length,
+              seedBase,
+              provider,
+              path: first.path,
+              url: first.url,
+              attachment: first.attachment,
+              width: first.width,
+              height: first.height,
+              seed: seedBase,
+              prompt: args.prompt,
+              cost: totalCost,
+              format,
+              ...(warnings.length ? { warnings } : {}),
+            })
+          } catch (err) {
+            throw new Error(sanitizeErrorAndLogs(err.message || err))
+          }
+        },
+      }),
+    )
+  }, 'dsh-image-gen: tool generate_responsive_mockups')
+}

package/lib/tools/sketch.js

@@ -0,0 +1,167 @@
+// sketch — sketch_to_image tool (#146)
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import {
+  makeProviders,
+  toLosslessJson,
+} from '../providers.js'
+import { resolveConversationImage, analyzeImageWithVision } from '../resolve-image.js'
+import { calculateGenerationCost, assertBudgetAvailable } from '../cost-meter.js'
+import { trackAndAssertLoopGuard } from '../loop-guard.js'
+import { sanitizeErrorAndLogs } from '../security.js'
+
+const SKETCH_PROMPT_SUFFIX =
+  'Detailed finished artwork derived from the provided line sketch. '
+  + 'Preserve the original composition, geometry, and proportions of the sketch. '
+  + 'Fill with coherent materials, lighting, and color while keeping the silhouette faithful.'
+
+function isSvgSource(source) {
+  const mt = String(source?.mediaType || '').toLowerCase()
+  if (mt.includes('svg')) return true
+  const head = source?.bytes ? Buffer.from(source.bytes).subarray(0, 256).toString('utf8') : ''
+  return head.includes('<svg')
+}
+
+export function registerSketchTools(ctx, deps) {
+  const {
+    live,
+    saveAndAttachResult,
+    slugify,
+    resolveApiKey,
+  } = deps
+
+  ctx.effect(() => {
+    ctx.tools.register(
+      defineTool({
+        name: 'sketch_to_image',
+        description:
+          'Turn a rough sketch, wireframe, or line drawing into a finished illustration (#146). '
+          + 'Accepts a raster sketch (PNG/JPEG) or SVG outline plus a text prompt. '
+          + 'Uses image-to-image with lower denoise strength so composition and proportions of the sketch are preserved. '
+          + 'If image is omitted or "latest", resolves the most recent image from the conversation session.',
+        parameters: {
+          prompt: {
+            type: 'string',
+            required: true,
+            description: 'What the finished image should look like (style, materials, lighting, mood).',
+          },
+          image: {
+            type: 'string',
+            description: 'Path or attachment id of the sketch. Defaults to "latest" to auto-resolve from session history.',
+          },
+          strength: {
+            type: 'number',
+            description: 'Denoise strength 0.1-1.0. Lower keeps more of the sketch geometry (default 0.45).',
+          },
+          output_name: {
+            type: 'string',
+            description: 'Optional file name stem for the saved image.',
+          },
+          output_dir: {
+            type: 'string',
+            description: 'Optional custom directory to write the image into.',
+          },
+        },
+        output: {
+          schema: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              summary: { type: 'string' },
+              path: { type: 'string' },
+              url: { type: 'string' },
+              width: { type: 'number' },
+              height: { type: 'number' },
+              seed: { type: 'number' },
+              provider: { type: 'string' },
+              cost: { type: 'number' },
+              format: { type: 'string' },
+              attachment: { type: 'object', additionalProperties: true },
+              inputFormat: { type: 'string' },
+              strength: { type: 'number' },
+            },
+          },
+        },
+        async execute(args, exec) {
+          try {
+            const cfg = live()
+            trackAndAssertLoopGuard(exec?.agent?.session?.id || 'default', { limit: cfg.loopGuardLimit })
+            const estimated = calculateGenerationCost({
+              provider: cfg.provider || 'fal',
+              model: cfg.model,
+              size: cfg.defaultSize || 'square_hd',
+              count: 1,
+            })
+            assertBudgetAvailable(estimated, cfg.dailyBudgetUsd)
+
+            const source = await resolveConversationImage(ctx, exec, args.image)
+            if (!source?.bytes) {
+              throw new Error('sketch_to_image: no sketch image resolved. Provide image path/attachment id or attach a sketch in the conversation.')
+            }
+            const svg = isSvgSource(source)
+            if (svg) {
+              // Normalize media type so providers that accept SVG get a correct data URL.
+              source.mediaType = 'image/svg+xml'
+            }
+
+            const vision = await analyzeImageWithVision(ctx, exec, source)
+            let effectivePrompt = `${args.prompt}\n\n${SKETCH_PROMPT_SUFFIX}`
+            if (vision.available && vision.summary) {
+              effectivePrompt += `\nSketch content: ${vision.summary}`
+            }
+
+            const provider = cfg.provider || 'fal'
+            const pdeps = {
+              fetchImpl: fetch,
+              resolveKey: (ref) => resolveApiKey(ctx, ref),
+              cfg,
+            }
+            const seed = Math.floor(Math.random() * 100000)
+            const strength = args.strength ?? 0.45
+            const format = cfg.defaultFormat || 'png'
+            const size = cfg.defaultSize || 'square_hd'
+
+            const job = {
+              prompt: effectivePrompt,
+              size,
+              format,
+              seed,
+              source,
+              strength,
+              provider,
+            }
+            const providers = makeProviders(pdeps, job)
+            const fn = providers[provider] || providers.fal || providers.custom
+            const gen = await fn(seed, effectivePrompt)
+
+            const stem = args.output_name ? slugify(args.output_name) : `sketch-${seed}`
+            const name = `${stem}.${format}`
+            const result = await saveAndAttachResult(ctx, exec, cfg, {
+              bytes: gen.bytes,
+              mediaType: gen.mediaType || 'image/png',
+              name,
+              stem,
+              prompt: args.prompt,
+              size,
+              format,
+              seed: gen.seed ?? seed,
+              provider,
+              model: cfg.model,
+              cost: gen.cost,
+              sourceUrl: gen.sourceUrl,
+              deliverAs: cfg.deliverAs || 'both',
+              args,
+              action: 'sketch_to_image',
+            })
+            result.inputFormat = svg ? 'svg' : String(source.mediaType || 'image/png')
+            result.strength = strength
+            if (vision.summary) result.visionAnalysis = vision.summary
+            return toLosslessJson(result)
+          } catch (err) {
+            throw new Error(sanitizeErrorAndLogs(err.message || err))
+          }
+        },
+      }),
+    )
+  }, 'dsh-image-gen: tool sketch_to_image')
+}

package/lib/tools/spritesheet.js

@@ -0,0 +1,151 @@
+// spritesheet — generate_spritesheet tool (#177)
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { makeProviders, toLosslessJson, saveAttachmentSafe } from '../providers.js'
+import { trackAndAssertLoopGuard } from '../loop-guard.js'
+import { sanitizeErrorAndLogs } from '../security.js'
+import {
+  ANIMATION_PRESETS,
+  clampFrames,
+  buildSpritesheetCss,
+  buildSpritesheetSvg,
+  buildFramePrompts,
+} from '../spritesheet-helpers.js'
+import { sizeToPixels } from '../providers.js'
+
+export function registerSpritesheetTools(ctx, deps) {
+  const { live, slugify, resolveApiKey } = deps
+
+  ctx.effect(() => {
+    ctx.tools.register(
+      defineTool({
+        name: 'generate_spritesheet',
+        description:
+          'Generate a 2D animation sprite sheet (#177): N consistent frames of a character/UI element in one horizontal strip, '
+          + 'plus CSS @keyframes with steps(N) for seamless playback. Supports animation types idle, walk, attack, pulse, hover.',
+        parameters: {
+          subject: {
+            type: 'string',
+            required: true,
+            description: 'Character or UI element description (e.g. "pixel knight with blue armor").',
+          },
+          animation: {
+            type: 'string',
+            description: 'Animation type: idle, walk, attack, pulse, or hover (default idle).',
+          },
+          frames: {
+            type: 'number',
+            description: 'Frame count: 4, 8, or 12 (default 8; walk uses 4 or 8).',
+          },
+          frame_size: {
+            type: 'string',
+            description: 'Named size for each frame (default square = 512x512, matches sheet tiles).',
+          },
+          duration: {
+            type: 'number',
+            description: 'Full loop duration in seconds (default 0.8).',
+          },
+          output_name: {
+            type: 'string',
+            description: 'File name stem / CSS class name (default spritesheet).',
+          },
+        },
+        output: {
+          schema: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              summary: { type: 'string' },
+              path: { type: 'string' },
+              url: { type: 'string' },
+              css: { type: 'string' },
+              cssPath: { type: 'string' },
+              frameCount: { type: 'number' },
+              animation: { type: 'string' },
+              format: { type: 'string' },
+              attachment: { type: 'object', additionalProperties: true },
+            },
+          },
+        },
+        async execute(args, exec) {
+          try {
+            const cfg = live()
+            trackAndAssertLoopGuard(exec?.agent?.session?.id || 'default', { limit: cfg.loopGuardLimit })
+            const animation = String(args.animation || 'idle').toLowerCase()
+            const animKey = ANIMATION_PRESETS[animation] ? animation : 'idle'
+            const frameCount = clampFrames(args.frames, animKey)
+            const provider = cfg.provider || 'fal'
+            const format = cfg.defaultFormat || 'png'
+            // square (512) matches tile slot; square_hd would overspend then downscale
+            const size = args.frame_size || 'square'
+            const seed = Math.floor(Math.random() * 100000)
+            const prompts = buildFramePrompts(args.subject, animKey, frameCount)
+
+            const frames = []
+            for (let i = 0; i < prompts.length; i++) {
+              const pdeps = {
+                fetchImpl: fetch,
+                resolveKey: (ref) => resolveApiKey(ctx, ref),
+                cfg,
+              }
+              const job = { prompt: prompts[i], size, format, seed: seed + i, provider }
+              const providers = makeProviders(pdeps, job)
+              const fn = providers[provider] || providers.fal || providers.custom
+              const gen = await fn(seed + i, prompts[i])
+              frames.push(gen)
+            }
+
+            const [frameW, frameH] = sizeToPixels(size)
+            const svg = buildSpritesheetSvg(frames, { frameW, frameH })
+            const svgBuffer = Buffer.from(svg, 'utf8')
+            const stem = slugify(args.output_name || 'spritesheet')
+            const sheetName = `${stem}-sheet.svg`
+            const { attachment, localUrl } = await saveAttachmentSafe(ctx, {
+              bytes: svgBuffer,
+              mediaType: 'image/svg+xml',
+              name: sheetName,
+            })
+
+            const sessionCwd = exec?.agent?.session?.header?.cwd
+            const outDir = path.resolve(sessionCwd || process.cwd(), cfg.outputDir || 'generated/images')
+            await mkdir(outDir, { recursive: true })
+            const filePath = path.join(outDir, sheetName)
+            await writeFile(filePath, svgBuffer)
+
+            const durationSec = Number(args.duration) > 0 ? Number(args.duration) : 0.8
+            const css = buildSpritesheetCss({
+              frameCount,
+              frameW,
+              frameH,
+              durationSec,
+              name: stem,
+            })
+            const cssPath = path.join(outDir, `${stem}.css`)
+            await writeFile(cssPath, css, 'utf8')
+
+            const summary = `### Sprite sheet (${animKey}, ${frameCount} frames)\n`
+              + `- **Sheet**: \`${filePath}\` (${frameW * frameCount}×${frameH})\n`
+              + `- **CSS**: \`${cssPath}\` — \`animation: ${stem} ${durationSec}s steps(${frameCount}) infinite\`\n\n`
+              + `![${stem}](${localUrl || filePath})`
+
+            return toLosslessJson({
+              summary,
+              path: filePath,
+              url: localUrl,
+              css,
+              cssPath,
+              frameCount,
+              animation: animKey,
+              format: 'svg',
+              attachment,
+            })
+          } catch (err) {
+            throw new Error(sanitizeErrorAndLogs(err.message || err))
+          }
+        },
+      }),
+    )
+  }, 'dsh-image-gen: tool generate_spritesheet')
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goodandready/dsh-image-gen",
-  "version": "0.10.24",
-  "description": "Image generation for DeepSeek Harness: a generate_image tool with pluggable providers \u2014 the FAL queue, any OpenAI-compatible images API, or a ChatGPT/Grok subscription with no API key at all. The picture is shown inline in the conversation; the model receives either a link (works with any chat model) or the image itself (needs dsh-vision-bridge or a vision-capable model).",
+  "version": "0.10.26",
+  "description": "Image generation for DeepSeek Harness: a generate_image tool with pluggable providers — the FAL queue, any OpenAI-compatible images API, or a ChatGPT/Grok subscription with no API key at all. The picture is shown inline in the conversation; the model receives either a link (works with any chat model) or the image itself (needs dsh-vision-bridge or a vision-capable model).",
   "keywords": [
     "deepseek-harness",
     "dsh",
@@ -36,7 +36,9 @@
     "lib/",
     "cordis.patch.yml",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "README.ru.md",
+    "README.zh.md"
   ],
   "license": "MIT",
   "engines": {
@@ -66,6 +68,7 @@
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "scripts": {
-    "test": "node --check lib/client.js && node --test test/*.test.mjs"
+    "test": "node scripts/build-client.mjs && node --check lib/client.js && node --test test/*.test.mjs",
+    "build:client": "node scripts/build-client.mjs"
   }
 }