@omega.js/manager 0.1.0

package/dist/services/assets/lib/derived.js

@@ -0,0 +1,113 @@
+/**
+ * The derived output NAMES every assets operation owns — the one home of the
+ * naming conventions, read by the writers that produce the files, by the
+ * `--reset-assets` cache clear (lib/reset.js), and by the reconcile that
+ * deletes what the current sources no longer derive (lib/reconcile.js).
+ *
+ * It has to be ONE list: a name a writer produces but the reconcile does not
+ * derive would be deleted on every walk and regenerated on the next one, so
+ * the two views of "what belongs under .omega/assets/" can never be allowed
+ * to drift apart.
+ *
+ * Everything here is relative to `.omega/assets/`; the shapes come from
+ * assets-config.js, so a new rule/template/platform is covered without a
+ * second registry to update.
+ */
+const { join } = require('node:path');
+
+const {
+  PROCESSING_RULES, SOCIAL_ICON_CONFIG, TEMPLATE_CONFIG, ICON_PLATFORMS, FAVICON_CONFIG,
+} = require('./assets-config.js');
+
+/** The two variants every logo source produces: the SVG as-is, and all-black. */
+const LOGO_VARIANTS = ['color', 'black'];
+
+/** The webmanifest — derived from config, not from the brandmark, so it is content-diffed. */
+const WEBMANIFEST_NAME = 'site.webmanifest';
+
+/**
+ * One logo variant's files, relative to the rule's output dir.
+ *
+ * @param {object} rule - A PROCESSING_RULES entry.
+ * @param {string} variant - A LOGO_VARIANTS entry.
+ * @returns {string[]} The variant SVG plus a PNG per ladder size.
+ */
+function logoVariantFiles(rule, variant) {
+  return [`${variant}-x.svg`, ...rule.sizes.map((size) => `${variant}-${size}.png`)];
+}
+
+/**
+ * The social profile icons, relative to SOCIAL_ICON_CONFIG.outputDir.
+ *
+ * @returns {string[]} The wrapped SVG plus a PNG per size.
+ */
+function socialIconFiles() {
+  return ['color-x.svg', ...SOCIAL_ICON_CONFIG.sizes.map((size) => `color-${size}.png`)];
+}
+
+/**
+ * The favicon IMAGES, relative to FAVICON_CONFIG.outputDir — the PNG ladder
+ * plus the multi-size .ico. The webmanifest is not here: it derives from
+ * config rather than from the brandmark, so it is diffed differently.
+ *
+ * @returns {string[]} File names.
+ */
+function faviconImageFiles() {
+  return [...FAVICON_CONFIG.files.map((file) => file.name), 'favicon.ico'];
+}
+
+/**
+ * One PSD template's exports.
+ *
+ * @param {object} config - A TEMPLATE_CONFIG entry.
+ * @returns {string[]} Paths relative to `.omega/assets/`.
+ */
+function templateExportFiles(config) {
+  return (config.exports || [{ suffix: '' }])
+    .map((exp) => join(config.outputDir, `${config.outputName}${exp.suffix || ''}.png`));
+}
+
+/**
+ * The platform app icons.
+ *
+ * @returns {Array<{ platform: string, format: string, file: string }>} `file`
+ *   is relative to `.omega/assets/`.
+ */
+function appIconFiles() {
+  return Object.entries(ICON_PLATFORMS).map(([platform, { format }]) => ({
+    platform,
+    format,
+    file: join('app', platform, `icon.${format}`),
+  }));
+}
+
+/**
+ * Every directory under `.omega/assets/` an assets operation writes into —
+ * the reconcile's output BOUNDARY. Nested entries are dropped (a recursive
+ * walk of `social` already covers `social/brandmark`), so each file is
+ * visited once.
+ *
+ * @returns {string[]} Paths relative to `.omega/assets/`.
+ */
+function assetsOutputDirs() {
+  const dirs = [...new Set([
+    ...Object.values(PROCESSING_RULES).map((rule) => rule.outputDir),
+    SOCIAL_ICON_CONFIG.outputDir,
+    ...Object.values(TEMPLATE_CONFIG).map((config) => config.outputDir),
+    ...Object.keys(ICON_PLATFORMS).map((platform) => join('app', platform)),
+    FAVICON_CONFIG.outputDir,
+  ])];
+
+  return dirs.filter((dir) => !dirs.some((other) => other !== dir && dir.startsWith(`${other}/`)));
+}
+
+module.exports = {
+  LOGO_VARIANTS,
+  WEBMANIFEST_NAME,
+  logoVariantFiles,
+  socialIconFiles,
+  faviconImageFiles,
+  templateExportFiles,
+  appIconFiles,
+  assetsOutputDirs,
+};

package/dist/services/assets/lib/font-loader.js

@@ -0,0 +1,67 @@
+/**
+ * Font loader for wordmark/combomark generation — resolves `brand.font`
+ * (a font filename without extension, e.g. `Inter-Bold`) to a parsed
+ * opentype.js Font.
+ *
+ * Search order: the brand repo's own `assets/fonts/` first, then the
+ * system font directories. omega-manager instead PACKAGED the company's
+ * commercial fonts (CromaSans/NowAlt — licensed, so they can't ship in a
+ * published package) and defaulted every brand to CromaSans-ExtraBold via
+ * a hardcoded alias table; the port has no packaged fonts and no default —
+ * the brand owns its font choice.
+ */
+const { join } = require('node:path');
+const { homedir } = require('node:os');
+const jetpack = require('fs-jetpack');
+const opentype = require('opentype.js');
+
+const FONT_EXTENSIONS = ['.otf', '.ttf', '.woff'];
+
+const SYSTEM_FONT_DIRS = [
+  join(homedir(), 'Library', 'Fonts'),
+  '/Library/Fonts',
+  '/System/Library/Fonts',
+];
+
+/**
+ * Find a font file by name (without extension).
+ *
+ * @param {string} name - Font filename, e.g. 'Inter-Bold'
+ * @param {string} brandRoot - Brand repo root (its assets/fonts/ is searched first)
+ * @returns {string|null} Full path to the font file, or null
+ */
+function findFontFile(name, brandRoot) {
+  const dirs = [join(brandRoot, 'assets', 'fonts'), ...SYSTEM_FONT_DIRS];
+
+  for (const dir of dirs) {
+    for (const ext of FONT_EXTENSIONS) {
+      const filePath = join(dir, `${name}${ext}`);
+      if (jetpack.exists(filePath)) {
+        return filePath;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Load and parse a font.
+ *
+ * @param {string} name - Font filename without extension
+ * @param {string} brandRoot - Brand repo root
+ * @returns {Object|null} opentype.js Font, or null when no file was found
+ */
+function loadFont(name, brandRoot) {
+  const fontPath = findFontFile(name, brandRoot);
+  if (!fontPath) {
+    return null;
+  }
+
+  const buffer = jetpack.read(fontPath, 'buffer');
+  // opentype.parse expects an ArrayBuffer
+  const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+  return opentype.parse(arrayBuffer);
+}
+
+module.exports = { loadFont, findFontFile };

package/dist/services/assets/lib/reconcile.js

@@ -0,0 +1,122 @@
+/**
+ * Assets reconcile (#636) — every file under `.omega/assets/` derives from the
+ * brand's sources and config, so the walk that writes them also DELETES the
+ * ones those sources no longer derive. Dropping `assets/logo/wordmark.svg` is
+ * a real removal: the wordmark's variants and ladders go with it, not on the
+ * next hand-deletion of the cache.
+ *
+ * Deleting is safe HERE and only here: `.omega/assets/` is the machine-owned,
+ * gitignored cache the reset already clears (lib/reset.js), and every file in
+ * it is regenerable from the brand's committed sources. The brand's own
+ * collateral (`assets/logo/*.svg`, `assets/templates/*.psd`) is a SOURCE and
+ * is never touched.
+ *
+ * Two locks keep it honest: the derived set comes from the SAME names the
+ * writers generate (lib/derived.js), and the diff runs only inside the
+ * operations' own output dirs — a file the assets service never writes into
+ * cannot be reached from here.
+ */
+const { join } = require('node:path');
+const fs = require('node:fs');
+const jetpack = require('fs-jetpack');
+
+const { PROCESSING_RULES, SOCIAL_ICON_CONFIG, TEMPLATE_CONFIG, FAVICON_CONFIG } = require('./assets-config.js');
+const {
+  LOGO_VARIANTS, WEBMANIFEST_NAME, logoVariantFiles, socialIconFiles,
+  faviconImageFiles, templateExportFiles, appIconFiles, assetsOutputDirs,
+} = require('./derived.js');
+
+/**
+ * The FULL set of files the brand's current sources derive, exactly as the
+ * write operations name them. A logo source or a PSD that isn't in the brand
+ * derives nothing — which is what makes a removed source remove its outputs.
+ *
+ * The brandmark is guaranteed by the service's setup, so the operations that
+ * read it alone (social icons, favicons, app icons) always derive their set.
+ *
+ * @param {string} brandRoot - Absolute brand-monorepo root.
+ * @returns {Set<string>} Paths relative to `.omega/assets/`.
+ */
+function derivedAssetFiles(brandRoot) {
+  const files = [];
+
+  for (const rule of Object.values(PROCESSING_RULES)) {
+    if (!jetpack.exists(join(brandRoot, rule.source))) {
+      continue;
+    }
+    for (const variant of LOGO_VARIANTS) {
+      files.push(...logoVariantFiles(rule, variant).map((name) => join(rule.outputDir, name)));
+    }
+  }
+
+  files.push(...socialIconFiles().map((name) => join(SOCIAL_ICON_CONFIG.outputDir, name)));
+
+  for (const [name, config] of Object.entries(TEMPLATE_CONFIG)) {
+    // The brand's PSD is the source — a template it does not carry (and the
+    // company root could not seed) exports nothing
+    if (!jetpack.exists(join(brandRoot, 'assets', 'templates', `${name}.psd`))) {
+      continue;
+    }
+    files.push(...templateExportFiles(config));
+  }
+
+  files.push(...appIconFiles().map((entry) => entry.file));
+  files.push(...faviconImageFiles().map((name) => join(FAVICON_CONFIG.outputDir, name)));
+  files.push(join(FAVICON_CONFIG.outputDir, WEBMANIFEST_NAME));
+
+  return new Set(files);
+}
+
+/**
+ * Every file under a directory, relative to it.
+ *
+ * @param {string} dir - Absolute directory.
+ * @returns {string[]} Relative paths.
+ */
+function filesUnder(dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => (entry.isDirectory()
+    ? filesUnder(join(dir, entry.name)).map((nested) => join(entry.name, nested))
+    : [entry.name]));
+}
+
+/**
+ * Delete the files inside the assets operations' output dirs that the brand's
+ * current sources no longer derive. Runs AFTER the write operations, so a file
+ * this same walk just generated (or a PSD it just seeded) is already derived.
+ *
+ * @param {object} args
+ * @param {string} args.brandRoot - Absolute brand-monorepo root.
+ * @param {string} args.outDir - The brand's `.omega/assets/`.
+ * @param {boolean} [args.dryRun] - Report what would go, delete nothing.
+ * @returns {{ removed: string[] }} The relative paths that were strays (and,
+ *   outside a dry run, are now gone).
+ */
+function reconcileAssets({ brandRoot, outDir, dryRun = false }) {
+  const derived = derivedAssetFiles(brandRoot);
+  const removed = [];
+
+  for (const dir of assetsOutputDirs()) {
+    const base = join(outDir, dir);
+
+    if (jetpack.exists(base) !== 'dir') {
+      continue;
+    }
+
+    for (const relative of filesUnder(base)) {
+      const path = join(dir, relative);
+
+      if (derived.has(path)) {
+        continue;
+      }
+
+      if (!dryRun) {
+        jetpack.remove(join(base, relative));
+      }
+      removed.push(path);
+    }
+  }
+
+  return { removed: removed.sort() };
+}
+
+module.exports = { derivedAssetFiles, reconcileAssets };

package/dist/services/assets/lib/reset.js

@@ -0,0 +1,118 @@
+/**
+ * Assets cache invalidation: the force refresh behind `omega manage
+ * --reset-assets` (#214). Every assets operation is mtime-diffed, so a
+ * converged brand regenerates nothing; when a derived file is wrong for a
+ * reason no timestamp records (a hand-mangled export, a sharp/ag-psd
+ * upgrade that renders differently), the only lever was hand-deleting
+ * `.omega/assets/`. omega-manager had `--reset-templates` /
+ * `--reset-logos` for exactly this.
+ *
+ * Invalidation IS deletion here: `isStale()` calls a missing derived file
+ * stale, so removing a kind's outputs is precisely what makes the same walk
+ * regenerate them, with no second freshness mechanism to keep in sync.
+ *
+ * Only `.omega/assets/` is cache. The brand's committed collateral
+ * (`assets/logo/*.svg`, `assets/templates/*.psd`) is a SOURCE and is never
+ * resettable: a reset that ate the PSD an operator edited by hand would be
+ * unrecoverable.
+ *
+ * The two kinds together are the whole cache: `templates` is the PSD export
+ * PNGs, `logos` is everything the logo sources derive (variants, app icon
+ * containers, social icons, favicons).
+ */
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+
+const {
+  PROCESSING_RULES, SOCIAL_ICON_CONFIG, TEMPLATE_CONFIG, FAVICON_CONFIG,
+} = require('./assets-config.js');
+const { templateExportFiles, appIconFiles } = require('./derived.js');
+
+const RESET_KINDS = ['logos', 'templates'];
+
+/**
+ * The derived paths a kind owns, relative to the out dir. Both lists come
+ * from the shared name lib (derived.js) so a new rule/template/platform is
+ * covered without a second registry to update.
+ *
+ * @param {string} kind - A RESET_KINDS entry.
+ * @returns {string[]} Relative paths (dirs for whole-output operations,
+ *   files where one dir holds more than one kind's output).
+ */
+function kindPaths(kind) {
+  if (kind === 'templates') {
+    // Files, not dirs: `app/macos` also holds the icons operation's .icns
+    return Object.values(TEMPLATE_CONFIG).flatMap(templateExportFiles);
+  }
+
+  return [
+    ...Object.values(PROCESSING_RULES).map((rule) => rule.outputDir),
+    SOCIAL_ICON_CONFIG.outputDir,
+    FAVICON_CONFIG.outputDir,
+    ...appIconFiles().map((entry) => entry.file),
+  ];
+}
+
+/**
+ * The kinds a run asked to reset. Mirrors the `--migration` idiom: the bare
+ * flag means all of them, a value names one (or a comma list). An unknown
+ * kind throws, because a typo that quietly reset everything (or nothing) is
+ * worse than a stopped run.
+ *
+ * @param {boolean|string|undefined} flag - options.resetAssets.
+ * @returns {string[]} Kinds in RESET_KINDS order, deduped.
+ */
+function resolveResetKinds(flag) {
+  if (!flag) {
+    return [];
+  }
+
+  if (flag === true) {
+    return [...RESET_KINDS];
+  }
+
+  const asked = String(flag).split(',').map((kind) => kind.trim()).filter(Boolean);
+  const unknown = asked.filter((kind) => !RESET_KINDS.includes(kind));
+
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown --reset-assets kind(s): ${unknown.join(', ')}. `
+      + `Available: ${RESET_KINDS.join(', ')} (bare --reset-assets resets both).`,
+    );
+  }
+
+  return RESET_KINDS.filter((kind) => asked.includes(kind));
+}
+
+/**
+ * Clear the derived outputs of the given kinds.
+ *
+ * @param {object} args
+ * @param {string} args.outDir - The brand's `.omega/assets/`.
+ * @param {string[]} args.kinds - Kinds from resolveResetKinds().
+ * @param {boolean} [args.dryRun] - Report what would go, delete nothing.
+ * @returns {{ kinds: string[], removed: string[] }} The relative paths that
+ *   existed (and, outside a dry run, are now gone).
+ */
+function resetAssetsCache({ outDir, kinds, dryRun = false }) {
+  const removed = [];
+
+  for (const kind of kinds) {
+    for (const relative of kindPaths(kind)) {
+      const target = join(outDir, relative);
+
+      if (!jetpack.exists(target)) {
+        continue;
+      }
+
+      if (!dryRun) {
+        jetpack.remove(target);
+      }
+      removed.push(relative);
+    }
+  }
+
+  return { kinds, removed };
+}
+
+module.exports = { RESET_KINDS, resolveResetKinds, resetAssetsCache };

package/dist/services/assets/lib/svg-logo-generator.js

@@ -0,0 +1,154 @@
+/**
+ * SVG logo generator — wordmark and combomark SVGs via opentype.js
+ * text-to-path conversion. All text is converted to path outlines so the
+ * SVGs are self-contained (no font dependency at render time).
+ */
+
+/**
+ * Generate a wordmark SVG (text-only logo).
+ *
+ * @param {string} brandName - The brand name text
+ * @param {Object} font - opentype.js Font object
+ * @returns {string} SVG markup
+ */
+function generateWordmark(brandName, font) {
+  const fontSize = 72;
+  const fill = '#000000';
+
+  const path = font.getPath(brandName, 0, 0, fontSize);
+  const bbox = path.getBoundingBox();
+
+  const width = bbox.x2 - bbox.x1;
+  const height = bbox.y2 - bbox.y1;
+
+  // Translate path so it starts at origin
+  const translateX = -bbox.x1;
+  const translateY = -bbox.y1;
+
+  const pathData = path.toPathData(4);
+
+  return buildSvg(width, height, [
+    `<path d="${pathData}" fill="${fill}" transform="translate(${round(translateX)}, ${round(translateY)})"/>`,
+  ]);
+}
+
+/**
+ * Generate a combomark SVG (brandmark left, text right).
+ *
+ * @param {string} brandName - The brand name text
+ * @param {string} brandmarkSvg - Raw SVG content of the brandmark
+ * @param {Object} font - opentype.js Font object
+ * @returns {string} SVG markup
+ */
+function generateCombomark(brandName, brandmarkSvg, font) {
+  const fontSize = 72;
+  const fill = '#000000';
+  const gapRatio = 0.3; // Gap between brandmark and text as fraction of brandmark height
+
+  const textPath = font.getPath(brandName, 0, 0, fontSize);
+  const textBbox = textPath.getBoundingBox();
+  const textWidth = textBbox.x2 - textBbox.x1;
+  const textHeight = textBbox.y2 - textBbox.y1;
+
+  const viewBox = parseBrandmarkViewBox(brandmarkSvg);
+  const brandmarkAspect = viewBox.width / viewBox.height;
+
+  // Scale brandmark to match text height
+  const brandmarkHeight = textHeight;
+  const brandmarkWidth = brandmarkHeight * brandmarkAspect;
+
+  // Layout: [brandmark] [gap] [text]
+  const gapWidth = brandmarkHeight * gapRatio;
+  const totalWidth = brandmarkWidth + gapWidth + textWidth;
+  const totalHeight = Math.max(brandmarkHeight, textHeight);
+
+  const brandmarkX = 0;
+  const brandmarkY = (totalHeight - brandmarkHeight) / 2;
+
+  const textOffsetX = brandmarkWidth + gapWidth - textBbox.x1;
+  const textOffsetY = (totalHeight - textHeight) / 2 - textBbox.y1;
+
+  const textPathData = textPath.toPathData(4);
+
+  const brandmarkInner = extractSvgInner(brandmarkSvg);
+  const viewBoxStr = `${viewBox.x} ${viewBox.y} ${viewBox.width} ${viewBox.height}`;
+
+  return buildSvg(totalWidth, totalHeight, [
+    // Nested <svg> preserves the brandmark's viewBox so the renderer handles
+    // content scaling and centering automatically (no manual transform needed)
+    `<svg x="${round(brandmarkX)}" y="${round(brandmarkY)}" width="${round(brandmarkWidth)}" height="${round(brandmarkHeight)}" viewBox="${viewBoxStr}">`,
+    ...brandmarkInner.map((line) => `  ${line}`),
+    `</svg>`,
+    `<path d="${textPathData}" fill="${fill}" transform="translate(${round(textOffsetX)}, ${round(textOffsetY)})"/>`,
+  ]);
+}
+
+/**
+ * Build a clean, minimal SVG wrapper.
+ */
+function buildSvg(width, height, innerContent) {
+  const w = round(width);
+  const h = round(height);
+
+  return [
+    `<?xml version="1.0" encoding="UTF-8"?>`,
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}" width="100%" height="100%">`,
+    ...innerContent.map((line) => `  ${line}`),
+    `</svg>`,
+    ``,
+  ].join('\n');
+}
+
+/**
+ * Parse brandmark SVG viewBox dimensions.
+ */
+function parseBrandmarkViewBox(svgContent) {
+  const match = svgContent.match(/viewBox="([^"]+)"/);
+  if (!match) {
+    return { x: 0, y: 0, width: 100, height: 100 };
+  }
+
+  const [x, y, width, height] = match[1].split(/\s+/).map(Number);
+  return { x, y, width, height };
+}
+
+/**
+ * Extract inner content from an SVG (everything between the opening <svg>
+ * and closing </svg>). Preserves <g> groups, transforms, and all element
+ * types; strips comments and vendor-specific attributes.
+ */
+function extractSvgInner(svgContent) {
+  const openMatch = svgContent.match(/<svg\s[^>]*>/);
+  if (!openMatch) {
+    return [];
+  }
+
+  const innerStart = openMatch.index + openMatch[0].length;
+  const innerEnd = svgContent.lastIndexOf('</svg>');
+  if (innerEnd <= innerStart) {
+    return [];
+  }
+
+  let inner = svgContent.slice(innerStart, innerEnd);
+
+  inner = inner.replace(/<!--[\s\S]*?-->/g, '');
+  inner = inner.replace(/<defs\s*\/>/g, '');
+  inner = inner.replace(/\s+vectornator:\w+="[^"]*"/g, '');
+  inner = inner.replace(/\s+xmlns:\w+="[^"]*"/g, '');
+  inner = inner.replace(/\s+xml:space="[^"]*"/g, '');
+  inner = inner.replace(/\s+opacity="1"/g, '');
+  inner = inner.replace(/\s+stroke="none"/g, '');
+
+  return inner.split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+}
+
+/**
+ * Round to 2 decimal places (for positions/dimensions).
+ */
+function round(n) {
+  return Math.round(n * 100) / 100;
+}
+
+module.exports = { generateWordmark, generateCombomark };

package/dist/services/assets/lib/svg-to-black.js

@@ -0,0 +1,32 @@
+/**
+ * Convert an SVG to a pure black version — the source for the `black-*`
+ * logo variants (and macOS template images, which must be pure black with
+ * alpha so the system can invert them in dark mode).
+ *
+ * Replaces all fills and strokes with #000000:
+ * - Removes <defs> blocks (gradients, filters, patterns)
+ * - Converts fill="..." / stroke="..." attributes (fill="none" preserved)
+ * - Converts fill:... / stroke:... in style attributes (none preserved)
+ */
+
+/**
+ * @param {string} svgContent - Raw SVG string
+ * @returns {string} SVG with all colors replaced by black
+ */
+function convertSvgToBlack(svgContent) {
+  let svg = svgContent;
+
+  svg = svg.replace(/<defs>[\s\S]*?<\/defs>/gi, '');
+  svg = svg.replace(/<defs\s*\/>/gi, '');
+
+  svg = svg.replace(/\bfill="(?!none)[^"]*"/g, 'fill="#000000"');
+  svg = svg.replace(/\bstroke="(?!none)[^"]*"/g, 'stroke="#000000"');
+
+  // fill:url(#...), fill:#hex, fill:rgb(...), fill:colorname inside style="..."
+  svg = svg.replace(/\bfill\s*:\s*(?!none)[^;}"]+/g, 'fill:#000000');
+  svg = svg.replace(/\bstroke\s*:\s*(?!none)[^;}"]+/g, 'stroke:#000000');
+
+  return svg;
+}
+
+module.exports = { convertSvgToBlack };

package/dist/services/assets/write/favicons.js

@@ -0,0 +1,82 @@
+/**
+ * Generate the web favicon set from the brandmark — the PNG ladder
+ * (favicon/apple-touch/android-chrome), a multi-size favicon.ico, and
+ * site.webmanifest — into `.omega/assets/favicon/`. Images are
+ * mtime-diffed against the brandmark; the webmanifest derives from
+ * config, so it's content-diffed instead.
+ */
+const { join } = require('node:path');
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+const sharp = require('sharp');
+const png2icons = require('png2icons');
+const { FAVICON_CONFIG } = require('../lib/assets-config.js');
+const { faviconImageFiles, WEBMANIFEST_NAME } = require('../lib/derived.js');
+const { isStale } = require('../../../lib/stale.js');
+
+module.exports = async function writeFavicons(context) {
+  const { brandConfig, brandmarkPath, outDir, options } = context;
+  const dryRun = options?.dryRun || false;
+
+  const outputDir = join(outDir, FAVICON_CONFIG.outputDir);
+
+  const staleImages = faviconImageFiles().filter((name) => isStale(brandmarkPath, join(outputDir, name)));
+
+  const brandName = brandConfig.brand.name;
+  const desiredManifest = JSON.stringify({
+    name: brandName,
+    short_name: brandName,
+    icons: [
+      { src: '/android-chrome-192x192.png', sizes: '192x192', type: 'image/png' },
+      { src: '/android-chrome-512x512.png', sizes: '512x512', type: 'image/png' },
+    ],
+    theme_color: '#ffffff',
+    background_color: '#ffffff',
+    display: 'standalone',
+  }, null, 2);
+
+  const manifestPath = join(outputDir, WEBMANIFEST_NAME);
+  const manifestStale = jetpack.read(manifestPath) !== desiredManifest;
+
+  if (staleImages.length === 0 && !manifestStale) {
+    console.log(`      ${chalk.green('✓')} Favicons in sync ${chalk.dim(`(${FAVICON_CONFIG.files.length + 2} files fresh)`)}`);
+    return { output: { favicons: { synced: true } } };
+  }
+
+  if (dryRun) {
+    const count = staleImages.length + (manifestStale ? 1 : 0);
+    console.log(`      ${chalk.yellow('[DRY RUN]')} Would generate ${chalk.cyan(count)} favicon files`);
+    return { output: { favicons: { planned: count } } };
+  }
+
+  jetpack.dir(outputDir);
+  let generated = 0;
+
+  for (const file of FAVICON_CONFIG.files) {
+    if (!staleImages.includes(file.name)) {
+      continue;
+    }
+    await sharp(brandmarkPath)
+      .resize(file.size, file.size, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+      .png()
+      .toFile(join(outputDir, file.name));
+    generated++;
+  }
+
+  if (staleImages.includes('favicon.ico')) {
+    const sourcePng = await sharp(brandmarkPath)
+      .resize(512, 512, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+      .png()
+      .toBuffer();
+    jetpack.write(join(outputDir, 'favicon.ico'), png2icons.createICO(sourcePng, png2icons.BICUBIC, 0, true));
+    generated++;
+  }
+
+  if (manifestStale) {
+    jetpack.write(manifestPath, desiredManifest);
+    generated++;
+  }
+
+  console.log(`      ${chalk.green('✓')} Generated ${chalk.bold(generated)} favicon files`);
+  return { output: { favicons: { generated } } };
+};