@open-assets/open-assets 0.1.11 → 0.2.0

package/lib/manifest.mjs

@@ -0,0 +1,132 @@
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+
+/**
+ * Get all export sizes from a collection (entries without a type field).
+ */
+export function flatSizes(collection) {
+  return (collection.export || []).filter((e) => !e.type);
+}
+
+/**
+ * Get all output actions from a collection (entries with a type field).
+ */
+export function flatOutputs(collection) {
+  return (collection.export || []).filter((e) => e.type);
+}
+
+/**
+ * Load and parse a config file from disk.
+ * @param {string} projectDir - Absolute path to the project directory
+ * @param {string} [configName="assets.json"] - Config filename
+ * @returns {object} Parsed config
+ * @throws {Error} If the file is missing or contains invalid JSON
+ */
+export function loadConfig(projectDir, configName = "assets.json") {
+  const configPath = resolve(projectDir, configName);
+  if (!existsSync(configPath)) {
+    throw new Error(`${configName} not found in ${projectDir}`);
+  }
+  try {
+    return JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch (err) {
+    throw new Error(`Invalid JSON in ${configName}: ${err.message}`);
+  }
+}
+
+/**
+ * Save a config to disk.
+ * @param {string} projectDir - Absolute path to the project directory
+ * @param {string} configName - Config filename
+ * @param {object} config - The config object to save
+ */
+export function saveConfig(projectDir, configName, config) {
+  const configPath = resolve(projectDir, configName);
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+/**
+ * Filter collections by ID and/or tag.
+ * @param {object[]} collections
+ * @param {{ collection?: string, tag?: string }} filters
+ * @returns {{ collections: object[], error?: string }}
+ */
+export function filterCollections(collections, filters = {}) {
+  let result = collections;
+  if (filters.collection) {
+    result = result.filter((c) => c.id === filters.collection);
+  }
+  if (filters.tag) {
+    result = result.filter((c) => (c.tags || []).includes(filters.tag));
+  }
+  if (result.length === 0) {
+    const filter = filters.collection
+      ? `collection "${filters.collection}"`
+      : `tag "${filters.tag}"`;
+    return { collections: [], error: `No collections matched ${filter} in config` };
+  }
+  return { collections: result };
+}
+
+/**
+ * Filter templates by name or label.
+ * @param {object[]} templates
+ * @param {string} [templateName] - If provided, filter to matching name/label
+ * @returns {object[]}
+ */
+export function filterTemplates(templates, templateName) {
+  if (!templateName) return templates;
+  return templates.filter(
+    (t) => t.name === templateName || t.label === templateName
+  );
+}
+
+/**
+ * Determine which sizes to render for a collection given CLI options.
+ * @param {object} collection - The collection from the config
+ * @param {{ width?: string|number, height?: string|number, size?: string, force?: boolean, platform?: string }} opts
+ * @returns {{ sizes: object[], warning?: string }}
+ */
+export function resolveRenderSizes(collection, opts = {}) {
+  const sourceW = collection.sourceSize.width;
+  const sourceH = collection.sourceSize.height;
+
+  if (opts.width && opts.height) {
+    const w = typeof opts.width === "number" ? opts.width : parseInt(opts.width);
+    const h = typeof opts.height === "number" ? opts.height : parseInt(opts.height);
+    return {
+      sizes: [{
+        name: `${w}x${h}`,
+        label: `${w}x${h}`,
+        size: { width: w, height: h },
+      }],
+    };
+  }
+
+  if (opts.size) {
+    const found = flatSizes(collection).find(
+      (s) => s.name === opts.size || s.label === opts.size
+    );
+    if (found) {
+      return { sizes: [found] };
+    }
+    return {
+      sizes: [],
+      warning: `size "${opts.size}" not found in collection "${collection.id}", skipping`,
+    };
+  }
+
+  if (opts.force) {
+    const sizes = flatSizes(collection);
+    return { sizes };
+  }
+
+  // Default: render at source size
+  return {
+    sizes: [{
+      name: `${sourceW}x${sourceH}`,
+      label: `${sourceW}x${sourceH}`,
+      size: { width: sourceW, height: sourceH },
+    }],
+  };
+}

package/lib/render.mjs

@@ -0,0 +1,219 @@
+import { resolve, join } from "path";
+import { mkdirSync, writeFileSync, copyFileSync, existsSync } from "fs";
+import { filterCollections, filterTemplates, resolveRenderSizes, flatOutputs } from "./manifest.mjs";
+
+/**
+ * @typedef {object} RenderDeps
+ * @property {(projectDir: string, htmlFile: string, w: number, h: number, sw: number, sh: number) => Promise<Buffer>} renderScreenshot
+ * @property {(projectDir: string, collection: object, outputConfig: object) => Promise<string>} runXcodeOutput
+ * @property {() => Promise<void>} closeBrowser
+ * @property {(projectDir: string) => object} readLockfile
+ * @property {(projectDir: string, data: object) => void} writeLockfile
+ * @property {(filePath: string) => string|null} computeChecksum
+ * @property {(lockData: object, assetKey: string, variantKey: string, checksum: string, outputPath: string) => boolean} isUpToDate
+ * @property {(lockData: object, assetKey: string, variantKey: string, checksum: string, outputPath: string) => void} recordExport
+ */
+
+/**
+ * Render assets according to the manifest and options.
+ *
+ * @param {string} projectDir - Absolute path to the project directory
+ * @param {object} manifest - Parsed manifest object
+ * @param {object} options - Render options from CLI
+ * @param {string} [options.collection] - Filter by collection ID
+ * @param {string} [options.tag] - Filter by tag
+ * @param {string} [options.template] - Filter by template name/label
+ * @param {string} [options.size] - Named export size
+ * @param {string} [options.format] - Output format override (png or jpg)
+ * @param {string|number} [options.width] - Custom width
+ * @param {string|number} [options.height] - Custom height
+ * @param {boolean} [options.force] - Export at all sizes and re-render (ignores cache)
+ * @param {string} [options.output] - Output directory path
+ * @param {boolean} [options.quiet] - Suppress logs
+ * @param {RenderDeps} deps - Injected dependencies
+ * @param {(msg: string) => void} [log] - Optional log function
+ * @returns {Promise<{ results: object[], skipped: number, elapsed: string, error?: string }>}
+ */
+export async function renderAssets(projectDir, manifest, options, deps, log) {
+  const noop = () => {};
+  const _log = log || noop;
+
+  // Filter collections
+  const { collections, error } = filterCollections(manifest.collections, {
+    collection: options.collection,
+    tag: options.tag,
+  });
+
+  if (error) {
+    return { results: [], skipped: 0, elapsed: "0.0s", error };
+  }
+
+  const outputDir = resolve(options.output || "./exports");
+  mkdirSync(outputDir, { recursive: true });
+
+  const lockData = deps.readLockfile(projectDir);
+  const results = [];
+  let skipped = 0;
+  const startTime = Date.now();
+
+  for (const col of collections) {
+    const sourceW = col.sourceSize.width;
+    const sourceH = col.sourceSize.height;
+
+    const templates = filterTemplates(col.templates, options.template);
+
+    const { sizes: sizesToRender, warning } = resolveRenderSizes(col, {
+      width: options.width,
+      height: options.height,
+      size: options.size,
+      force: options.force,
+    });
+
+    if (warning) {
+      _log(`  Warning: ${warning}`);
+      continue;
+    }
+
+    if (sizesToRender.length === 0) {
+      _log(`  No export sizes found for collection "${col.id}"`);
+      continue;
+    }
+
+    const singleTemplate = templates.length === 1;
+    const multipleSizes = sizesToRender.length > 1 || options.force;
+    // Single-template collections use flat layout with entry.name as filename
+    // Multi-template collections use subdirs per size
+    const useSubDirs = multipleSizes && !singleTemplate;
+
+    for (const entry of sizesToRender) {
+      const w = entry.size.width;
+      const h = entry.size.height;
+
+      const sizeDir = useSubDirs
+        ? join(outputDir, col.id, entry.name)
+        : join(outputDir, col.id);
+      mkdirSync(sizeDir, { recursive: true });
+
+      if (sizesToRender.length > 1) {
+        _log(`\n  ${entry.label} (${w}x${h})`);
+      }
+
+      for (const template of templates) {
+        // Determine output format from outFile extension or default to png
+        const outExt = entry.outFile
+          ? entry.outFile.split(".").pop().toLowerCase()
+          : "png";
+        const format = outExt === "jpg" || outExt === "jpeg" ? "jpeg" : "png";
+        const defaultExt = format === "jpeg" ? "jpg" : "png";
+
+        // Single-template: use entry.name as filename (e.g. logo-1024.png)
+        // Multi-template: use template.name as filename (e.g. 01-hero.png)
+        const fileName = singleTemplate && multipleSizes
+          ? `${entry.name}.${defaultExt}`
+          : `${template.name}.${defaultExt}`;
+
+        const outPath = entry.outFile
+          ? resolve(projectDir, entry.outFile.replace(/\{template\}/g, template.name))
+          : join(sizeDir, fileName);
+
+        const assetKey = `${col.id}/${template.name}`;
+        const variantKey = entry.name;
+        const srcPath = resolve(projectDir, template.src);
+        const checksum = deps.computeChecksum(srcPath);
+
+        // Skip if unchanged
+        if (
+          !options.force &&
+          checksum &&
+          deps.isUpToDate(lockData, assetKey, variantKey, checksum, outPath)
+        ) {
+          _log(
+            `  Skipping ${template.name} at ${w}x${h} (unchanged)`
+          );
+          skipped++;
+          continue;
+        }
+
+        _log(
+          `  Rendering ${template.name} at ${w}x${h}...`
+        );
+
+        const isSvg = template.src.endsWith(".svg");
+        if (isSvg && w === sourceW && h === sourceH) {
+          copyFileSync(srcPath, outPath.replace(`.${defaultExt}`, ".svg"));
+        }
+
+        // Ensure output directory exists when using outFile
+        if (entry.outFile) {
+          mkdirSync(resolve(projectDir, join(outPath, "..")), { recursive: true });
+        }
+
+        const buffer = await deps.renderScreenshot(
+          projectDir,
+          template.src,
+          w,
+          h,
+          sourceW,
+          sourceH,
+          { format, background: col.background }
+        );
+        writeFileSync(outPath, buffer);
+        results.push({
+          collection: col.id,
+          template: template.name,
+          path: outPath,
+          width: w,
+          height: h,
+          size: buffer.length,
+        });
+        if (checksum) {
+          deps.recordExport(lockData, assetKey, variantKey, checksum, outPath);
+        }
+        _log(`    → ${outPath}`);
+      }
+    }
+
+    // Handle outputs (xcode, copy-source, etc.)
+    const outputs = flatOutputs(col);
+    if (outputs.length > 0 && options.force) {
+      for (const output of outputs) {
+        if (output.type === "xcode") {
+          _log(`\n  Exporting to Xcode: ${output.path}`);
+          const path = await deps.runXcodeOutput(projectDir, col, output);
+          results.push({ collection: col.id, type: "xcode", path });
+        } else if (output.type === "copy-source") {
+          const format = output.format || "svg";
+          const copyDir = join(outputDir, col.id);
+          mkdirSync(copyDir, { recursive: true });
+          const matchingTemplates = templates.filter((t) => t.src.endsWith(`.${format}`));
+          for (const template of matchingTemplates) {
+            const srcPath = resolve(projectDir, template.src);
+            // Use entry name when single match, template name when multiple
+            const baseName = output.name && matchingTemplates.length === 1
+              ? output.name
+              : template.name;
+            const destPath = join(copyDir, `${baseName}.${format}`);
+            if (existsSync(srcPath)) {
+              copyFileSync(srcPath, destPath);
+              results.push({
+                collection: col.id,
+                template: template.name,
+                type: `copy-${format}`,
+                path: destPath,
+              });
+              _log(`    → ${destPath}`);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Persist lockfile
+  deps.writeLockfile(projectDir, lockData);
+
+  await deps.closeBrowser();
+
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+  return { results, skipped, elapsed: `${elapsed}s` };
+}

package/lib/renderer.mjs

@@ -1,6 +1,6 @@
 import { launch } from "puppeteer";
 import { resolve } from "path";
-import { writeFileSync, mkdirSync } from "fs";
+import { writeFileSync, mkdirSync, readdirSync, unlinkSync } from "fs";
 
 let browser = null;
 
@@ -19,8 +19,15 @@ export async function closeBrowser() {
 }
 
 /**
- * Render an HTML file to a PNG buffer at the given dimensions.
+ * Render an HTML file to an image buffer at the given dimensions.
  * Scales from sourceSize to target size via CSS zoom.
+ * @param {string} projectDir
+ * @param {string} htmlFile
+ * @param {number} width
+ * @param {number} height
+ * @param {number} sourceW
+ * @param {number} sourceH
+ * @param {{ format?: "png"|"jpeg", quality?: number, background?: string }} [options]
  */
 export async function renderScreenshot(
   projectDir,
@@ -28,7 +35,8 @@ export async function renderScreenshot(
   width,
   height,
   sourceW,
-  sourceH
+  sourceH,
+  options = {}
 ) {
   const b = await getBrowser();
   const page = await b.newPage();
@@ -48,10 +56,27 @@ export async function renderScreenshot(
     await new Promise((r) => setTimeout(r, 200));
   }
 
-  const buffer = await page.screenshot({
-    type: "png",
+  // Handle background: transparent by default for PNG, or use specified color
+  const bg = options.background;
+  if (bg) {
+    await page.evaluate((color) => {
+      document.documentElement.style.backgroundColor = color;
+    }, bg);
+  }
+
+  const format = options.format || "png";
+  const screenshotOpts = {
+    type: format,
     clip: { x: 0, y: 0, width, height },
-  });
+  };
+  if (format === "png" && !bg) {
+    screenshotOpts.omitBackground = true;
+  }
+  if (format === "jpeg" && options.quality) {
+    screenshotOpts.quality = options.quality;
+  }
+
+  const buffer = await page.screenshot(screenshotOpts);
 
   await page.close();
   return buffer;
@@ -68,14 +93,39 @@ export async function runXcodeOutput(projectDir, collection, outputConfig) {
 
   const outputDir = resolve(projectDir, outputConfig.path);
   mkdirSync(outputDir, { recursive: true });
-  const outputPath = resolve(outputDir, "AppIcon.png");
 
   const sw = collection.sourceSize.width;
   const sh = collection.sourceSize.height;
+  const filename = "AppIcon.png";
+  const outputPath = resolve(outputDir, filename);
+
+  // Remove stale images that don't match the current output filename
+  for (const entry of readdirSync(outputDir)) {
+    if (entry !== filename && /\.(png|jpg|jpeg)$/i.test(entry)) {
+      unlinkSync(resolve(outputDir, entry));
+    }
+  }
 
   const buffer = await renderScreenshot(projectDir, template.src, sw, sh, sw, sh);
   writeFileSync(outputPath, buffer);
 
+  const contentsJson = {
+    images: [
+      {
+        filename,
+        idiom: "universal",
+        platform: "ios",
+        size: `${sw}x${sh}`,
+      },
+    ],
+    info: {
+      author: "xcode",
+      version: 1,
+    },
+  };
+  const contentsPath = resolve(outputDir, "Contents.json");
+  writeFileSync(contentsPath, JSON.stringify(contentsJson, null, 2) + "\n");
+
   console.log(`Updated: ${outputPath}`);
   return outputPath;
 }

package/lib/server.mjs

@@ -2,7 +2,6 @@ import { createServer } from "http";
 import { readFileSync, existsSync, statSync, watch } from "fs";
 import { resolve, join, extname } from "path";
 import { fileURLToPath } from "url";
-import { renderScreenshot, runXcodeOutput, closeBrowser } from "./renderer.mjs";
 
 const __dirname = resolve(fileURLToPath(import.meta.url), "..");
 const VIEWER_PATH = join(__dirname, "..", "public", "viewer.html");
@@ -28,7 +27,7 @@ const MIME_TYPES = {
   ".webm": "video/webm",
 };
 
-function getMime(filePath) {
+export function getMime(filePath) {
   return MIME_TYPES[extname(filePath).toLowerCase()] || "application/octet-stream";
 }
 
@@ -52,11 +51,22 @@ function readBody(req) {
   });
 }
 
-export function startServer(projectDir, options = {}) {
+/**
+ * @param {string} projectDir
+ * @param {object} [options]
+ * @param {{ renderScreenshot: Function, runXcodeOutput: Function, closeBrowser: Function }} [renderer]
+ *   Optional renderer dependency injection. Falls back to importing ./renderer.mjs.
+ */
+export async function startServer(projectDir, options = {}, renderer) {
+  if (!renderer) {
+    renderer = await import("./renderer.mjs");
+  }
+  const { renderScreenshot, runXcodeOutput, closeBrowser } = renderer;
+
   const port = options.port || 3200;
   const host = options.host || "localhost";
   const quiet = options.quiet || false;
-  const manifestPath = options.manifestPath || resolve(projectDir, "manifest.json");
+  const manifestPath = options.manifestPath || resolve(projectDir, "assets.json");
   const staticDirs = (options.staticDirs || []).map((d) => resolve(d));
 
   const log = quiet ? () => {} : console.log.bind(console);
@@ -136,7 +146,7 @@ export function startServer(projectDir, options = {}) {
     // API: render screenshot (unified for all collection types)
     if (req.method === "POST" && pathname === "/api/render-screenshot") {
       try {
-        const { file, width, height, sourceW, sourceH } = JSON.parse(
+        const { file, width, height, sourceW, sourceH, background } = JSON.parse(
           await readBody(req)
         );
         if (!file || !width || !height) {
@@ -148,7 +158,7 @@ export function startServer(projectDir, options = {}) {
         const sw = sourceW || width;
         const sh = sourceH || height;
         log(`Rendering ${file} at ${width}x${height} (source ${sw}x${sh})...`);
-        const buffer = await renderScreenshot(projectDir, file, width, height, sw, sh);
+        const buffer = await renderScreenshot(projectDir, file, width, height, sw, sh, { background });
         res.writeHead(200, {
           "Content-Type": "image/png",
           "Content-Length": buffer.length,
@@ -171,7 +181,8 @@ export function startServer(projectDir, options = {}) {
           res.writeHead(404, { "Content-Type": "application/json" });
           return res.end(JSON.stringify({ ok: false, error: "Collection not found" }));
         }
-        const output = col.outputs?.[outputIndex || 0];
+        const outputs = (col.export || []).filter((e) => e.type);
+        const output = outputs[outputIndex || 0];
         if (!output) {
           res.writeHead(404, { "Content-Type": "application/json" });
           return res.end(JSON.stringify({ ok: false, error: "Output not found" }));
@@ -235,30 +246,50 @@ export function startServer(projectDir, options = {}) {
     res.end();
   });
 
-  server.listen(port, host, () => {
-    log();
-    log(`  open-assets dev server`);
-    log(`  ───────────────────────`);
-    log(`  Local:   http://${host}:${port}`);
-    if (host === "0.0.0.0") {
-      log(`  Network: http://<your-ip>:${port}`);
-    }
-    log(`  Project: ${projectDir}`);
-    if (staticDirs.length > 0) {
-      log(`  Static:  ${staticDirs.join(", ")}`);
-    }
-    log();
-  });
+  const maxRetries = 10;
+  let currentPort = port;
+  let resolved = false;
+
+  const actualPort = await new Promise((resolvePort) => {
+    function tryListen() {
+      server.once("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+          if (currentPort - port >= maxRetries) {
+            console.error(`Error: Ports ${port}–${currentPort} are all in use.`);
+            process.exit(1);
+          }
+          currentPort++;
+          server.close(() => tryListen());
+          return;
+        }
+        throw err;
+      });
 
-  server.on("error", (err) => {
-    if (err.code === "EADDRINUSE") {
-      console.error(`Error: Port ${port} is already in use.`);
-      console.error(`Try a different port: open-assets dev --port ${port + 1}`);
-      process.exit(1);
+      server.listen(currentPort, host, () => {
+        if (resolved) return;
+        resolved = true;
+        const displayHost = host === "0.0.0.0" ? "localhost" : host;
+        if (currentPort !== port) {
+          log();
+          log(`  Port ${port} is in use, using ${currentPort} instead.`);
+        }
+        log();
+        log(`  Open Assets is running on http://${displayHost}:${currentPort}`);
+        log();
+        log(`  Project: ${projectDir}`);
+        if (staticDirs.length > 0) {
+          log(`  Static:  ${staticDirs.join(", ")}`);
+        }
+        log();
+        resolvePort(currentPort);
+      });
     }
-    throw err;
+
+    tryListen();
   });
 
+  return { port: actualPort };
+
   function cleanup() {
     for (const w of watchers) w.close();
     for (const client of sseClients) client.end();

package/lib/validate.mjs

@@ -0,0 +1,93 @@
+import { existsSync } from "fs";
+import { resolve } from "path";
+import { flatSizes, flatOutputs } from "./manifest.mjs";
+
+/**
+ * Validate a config object and check that referenced files exist.
+ * Returns structured results instead of printing/exiting.
+ *
+ * @param {object} manifest - Parsed config object
+ * @param {string} projectDir - Absolute path to the project directory
+ * @returns {{ checks: Array<{ ok: boolean, message: string }>, errors: number }}
+ */
+export function validateConfig(manifest, projectDir) {
+  const checks = [];
+  const missingTemplates = [];
+  const emptyCollections = [];
+  let errors = 0;
+
+  const ok = (msg) => checks.push({ ok: true, message: msg });
+  const fail = (msg) => {
+    checks.push({ ok: false, message: msg });
+    errors++;
+  };
+
+  // Check top-level fields
+  if (manifest.name) {
+    ok(`name: "${manifest.name}"`);
+  } else {
+    fail("Missing top-level 'name' field");
+  }
+
+  if (Array.isArray(manifest.collections) && manifest.collections.length > 0) {
+    ok(`${manifest.collections.length} collection(s) defined`);
+  } else {
+    fail("Missing or empty 'collections' array");
+    return { checks, errors, missingTemplates, emptyCollections };
+  }
+
+  // Check each collection
+  const ids = new Set();
+  for (const col of manifest.collections) {
+    if (!col.id) {
+      fail("Collection missing 'id' field");
+      continue;
+    }
+    if (ids.has(col.id)) {
+      fail(`Duplicate collection id: "${col.id}"`);
+    }
+    ids.add(col.id);
+
+    if (!col.sourceSize || !col.sourceSize.width || !col.sourceSize.height) {
+      fail(`Collection "${col.id}" missing or invalid 'sourceSize'`);
+    } else {
+      ok(`Collection "${col.id}" sourceSize: ${col.sourceSize.width}\u00d7${col.sourceSize.height}`);
+    }
+
+    if (!col.templates || col.templates.length === 0) {
+      fail(`Collection "${col.id}" has no templates`);
+      emptyCollections.push({ collectionId: col.id });
+    } else {
+      for (const template of col.templates) {
+        if (!template.src) {
+          fail(`Collection "${col.id}" has a template without 'src'`);
+          continue;
+        }
+        const filePath = resolve(projectDir, template.src);
+        if (existsSync(filePath)) {
+          ok(`${template.src} exists`);
+        } else {
+          fail(`${template.src} not found`);
+          missingTemplates.push({
+            collectionId: col.id,
+            templateSrc: template.src,
+            templateName: template.name || template.label,
+          });
+        }
+      }
+    }
+
+    const sizes = flatSizes(col);
+    if (sizes.length > 0) {
+      ok(`Collection "${col.id}" has ${sizes.length} export size(s)`);
+    }
+
+    // Validate outputs (export entries with a type field)
+    const outputs = flatOutputs(col);
+    for (const output of outputs) {
+      ok(`Output: ${output.type}`);
+    }
+  }
+
+  return { checks, errors, missingTemplates, emptyCollections };
+}