purgetss 7.5.2 → 7.6.1

package/src/core/branding/tiapp-reader.js

@@ -0,0 +1,110 @@
+/**
+ * PurgeTSS - tiapp-reader
+ *
+ * Parses tiapp.xml and exposes just enough config for context-aware cleanup
+ * decisions. Uses fast-xml-parser under the hood when available, falls back
+ * to regex when the dep is unavailable.
+ *
+ * @fileoverview tiapp.xml parser for branding cleanup
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+
+let XMLParser = null
+try {
+  const mod = await import('fast-xml-parser')
+  XMLParser = mod.XMLParser
+} catch {
+  XMLParser = null
+}
+
+export function readTiapp(tiappPath) {
+  const result = {
+    exists: false,
+    storyboardEnabled: false,
+    portraitOnly: false,
+    defaultBgColor: null
+  }
+
+  if (!fs.existsSync(tiappPath)) return result
+
+  result.exists = true
+  const xml = fs.readFileSync(tiappPath, 'utf8')
+
+  if (XMLParser) return parseWithFastXml(xml, result)
+  return parseWithRegex(xml, result)
+}
+
+function parseWithFastXml(xml, result) {
+  try {
+    const parser = new XMLParser({
+      ignoreAttributes: false,
+      attributeNamePrefix: '@_',
+      parseAttributeValue: false,
+      parseTagValue: false,
+      trimValues: true
+    })
+    const doc = parser.parse(xml)
+
+    const ios = doc?.['ti:app']?.ios || doc?.ti?.app?.ios
+    if (ios) {
+      const sb = ios['enable-launch-screen-storyboard']
+      if (typeof sb === 'string' && sb.trim().toLowerCase() === 'true') {
+        result.storyboardEnabled = true
+      }
+      const bg = ios['default-background-color']
+      if (typeof bg === 'string' && bg.trim()) {
+        result.defaultBgColor = bg.trim()
+      }
+
+      const orientations = ios.orientations
+      if (orientations) {
+        const iphoneBlock = orientations.iphone
+        if (iphoneBlock !== undefined) {
+          const flat = JSON.stringify(iphoneBlock)
+          result.portraitOnly = !/Landscape/i.test(flat)
+        }
+      }
+    }
+    return result
+  } catch {
+    return parseWithRegex(xml, result)
+  }
+}
+
+function parseWithRegex(xml, result) {
+  if (/<enable-launch-screen-storyboard>\s*true\s*</i.test(xml)) {
+    result.storyboardEnabled = true
+  }
+
+  const bgMatch = xml.match(/<default-background-color>\s*(#[0-9A-Fa-f]{6,8})\s*</)
+  if (bgMatch) result.defaultBgColor = bgMatch[1]
+
+  if (/<orientations\b/i.test(xml) && !/UIInterfaceOrientationLandscape/i.test(xml)) {
+    result.portraitOnly = true
+  }
+
+  return result
+}
+
+export function detectProjectType(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, 'app'))) return 'alloy'
+  if (fs.existsSync(path.join(projectRoot, 'Resources'))) return 'classic'
+  return 'unknown'
+}
+
+export function resolveAndroidResRoot(projectRoot, projectType) {
+  if (projectType === 'alloy') return path.join(projectRoot, 'app', 'platform', 'android', 'res')
+  if (projectType === 'classic') return path.join(projectRoot, 'platform', 'android', 'res')
+  return null
+}
+
+export function hasAdaptiveIcons(projectRoot) {
+  const candidates = [
+    path.join(projectRoot, 'app', 'platform', 'android', 'res', 'mipmap-anydpi-v26'),
+    path.join(projectRoot, 'platform', 'android', 'res', 'mipmap-anydpi-v26')
+  ]
+  return candidates.some((c) => fs.existsSync(c))
+}

package/src/core/builders/tailwind-helpers.js

@@ -383,7 +383,7 @@ export function combineAllValues(base, defaultTheme) {
   allValues.contentWidth = combineKeys(configFile.theme, base.width, 'contentWidth')
   allValues.countDownDuration = combineKeys(configFile.theme, base.spacing, 'countDownDuration')
   allValues.elevation = combineKeys(configFile.theme, base.spacing, 'elevation')
-  allValues.fontFamily = combineKeys(configFile.theme, defaultTheme.fontFamily, 'fontFamily')
+  allValues.fontFamily = combineKeys(configFile.theme, {}, 'fontFamily')
   allValues.fontSize = combineKeys(configFile.theme, base.fontSize, 'fontSize')
   allValues.fontWeight = combineKeys(configFile.theme, defaultTheme.fontWeight, 'fontWeight')
   allValues.gap = combineKeys(configFile.theme, base.spacing, 'gap')

package/src/core/images/ensure-images-section.js

@@ -0,0 +1,57 @@
+/**
+ * PurgeTSS - Ensure `images:` section exists in purgetss/config.cjs
+ *
+ * Parallel to ensure-brand-section.js. When a project was initialized before
+ * the `images` command was introduced, its config.cjs won't have an `images:`
+ * key. On first invocation of `purgetss images`, we patch the file to insert
+ * the default block between `brand:` and `theme:` (or before `theme:` if
+ * `brand:` is not present yet). The user's existing keys are untouched.
+ *
+ * Also ensures `purgetss/images/` exists so the user can see where sources go,
+ * mirroring the `purgetss/fonts/` and `purgetss/brand/` conventions.
+ *
+ * @fileoverview Auto-injects the `images:` section on first `images` run
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import chalk from 'chalk'
+import { projectsConfigJS, projectsPurge_TSS_Images_Folder } from '../../shared/constants.js'
+import { logger } from '../branding/branding-logger.js'
+
+const IMAGES_BLOCK = `  images: {
+    quality: 85,             // JPEG/WebP/AVIF quality (0-100)
+    format: null,            // null = keep original; 'webp' | 'jpeg' | 'png' to convert every image
+    confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+  },
+`
+
+export function ensureImagesSection() {
+  if (!fs.existsSync(projectsPurge_TSS_Images_Folder)) {
+    fs.mkdirSync(projectsPurge_TSS_Images_Folder, { recursive: true })
+  }
+
+  if (!fs.existsSync(projectsConfigJS)) return
+
+  const original = fs.readFileSync(projectsConfigJS, 'utf8')
+
+  if (/^\s*images\s*:/m.test(original)) return
+
+  // Insert before the `theme:` key so the order stays purge → brand → images → theme.
+  const match = original.match(/(^\s*)theme\s*:/m)
+  if (!match) return
+
+  const patched = original.replace(match[0], `${IMAGES_BLOCK}${match[0]}`)
+
+  try {
+    fs.writeFileSync(projectsConfigJS, patched, 'utf8')
+    console.log()
+    logger.success(`Added ${chalk.cyan('images:')} section to ${chalk.cyan('./purgetss/config.cjs')} with default values.`)
+    console.log(`  Edit that block to customize defaults (quality, format).`)
+    console.log(`  CLI flags always win over config values.`)
+    console.log()
+  } catch (err) {
+    logger.warning(`Could not auto-add images: section to config.cjs (${err.message}).`)
+    logger.warning(`The command will still run using built-in defaults.`)
+  }
+}

package/src/core/images/gen-scales.js

@@ -0,0 +1,181 @@
+/**
+ * PurgeTSS - gen-scales
+ *
+ * For a single source image, generate the 8 Titanium multi-density variants:
+ *
+ *   Android (5 densities, each in its own mipmap/drawable folder):
+ *     res-mdpi    = 1/4 of source  (1× baseline)
+ *     res-hdpi    = 1.5/4 of source
+ *     res-xhdpi   = 2/4 of source  (2×)
+ *     res-xxhdpi  = 3/4 of source  (3×)
+ *     res-xxxhdpi = full source    (4×, maximum density)
+ *
+ *   iPhone (3 scales in one folder, suffix in filename):
+ *     @1x = 1/4 of source
+ *     @2x = 2/4 of source
+ *     @3x = 3/4 of source
+ *
+ * Convention inherited from Titanium Alloy: source images are treated as
+ * 4× (xxxhdpi/@4x) masters, and all other scales are derived from them.
+ *
+ * @fileoverview Scale a source image into the 8 Titanium density variants
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+import { logger } from '../branding/branding-logger.js'
+import { computeSvgDensity, readSvgSafely } from '../../shared/svg-utils.js'
+
+/**
+ * Read source image: for SVGs, uses readSvgSafely (buffer + metadata + viewBox
+ * warning); for raster images, reads metadata directly from the file path.
+ *
+ * @returns {Promise<{path: string, meta: Object, isSvg: boolean, buffer: Buffer|null}>}
+ */
+async function readSource(sourceFile) {
+  const isSvg = path.extname(sourceFile).toLowerCase() === '.svg'
+  if (isSvg) {
+    const { buffer, meta } = await readSvgSafely(sourceFile, { logger })
+    return { path: sourceFile, meta, isSvg: true, buffer }
+  }
+  const meta = await sharp(sourceFile).metadata()
+  return { path: sourceFile, meta, isSvg: false, buffer: null }
+}
+
+/**
+ * Build a Sharp pipeline for the requested scale. For SVG sources, density is
+ * computed so the rasterization lands at ~2× target — avoiding the pixel limit
+ * regardless of viewBox size.
+ */
+function buildScalePipeline(src, targetMax) {
+  if (src.isSvg) {
+    const naturalMax = Math.max(src.meta.width, src.meta.height)
+    // 2× target for antialiasing headroom before Sharp's downsample.
+    const density = computeSvgDensity(naturalMax, targetMax * 2)
+    return sharp(src.buffer, { density, limitInputPixels: false })
+  }
+  return sharp(src.path)
+}
+
+export const ANDROID_SCALES = Object.freeze([
+  { name: 'res-mdpi',    factor: 1 / 4 },
+  { name: 'res-hdpi',    factor: 1.5 / 4 },
+  { name: 'res-xhdpi',   factor: 2 / 4 },
+  { name: 'res-xxhdpi',  factor: 3 / 4 },
+  { name: 'res-xxxhdpi', factor: 4 / 4 }
+])
+
+export const IPHONE_SCALES = Object.freeze([
+  { suffix: '',    factor: 1 / 4 },
+  { suffix: '@2x', factor: 2 / 4 },
+  { suffix: '@3x', factor: 3 / 4 }
+])
+
+/**
+ * Scale a source image into all Android density variants.
+ *
+ * @param {string} sourceFile - Absolute path to source image
+ * @param {string} relPath - Path inside the source root (e.g. 'buttons/btn.png')
+ * @param {string} androidBaseDir - e.g. <project>/app/assets/android/images
+ * @param {Object} opts
+ * @param {string|null} [opts.format] - 'webp'|'jpeg'|'png'|null (null = keep original)
+ * @param {number} [opts.quality=85]
+ * @returns {Promise<string[]>} Paths written
+ */
+export async function genAndroidScales(sourceFile, relPath, androidBaseDir, opts = {}) {
+  const { format = null, quality = 85 } = opts
+  const src = await readSource(sourceFile)
+  const written = []
+
+  for (const { name, factor } of ANDROID_SCALES) {
+    const targetWidth = Math.max(1, Math.round(src.meta.width * factor))
+    const targetHeight = Math.max(1, Math.round(src.meta.height * factor))
+
+    const outDir = path.join(androidBaseDir, name, path.dirname(relPath))
+    fs.mkdirSync(outDir, { recursive: true })
+
+    const outPath = path.join(outDir, renameWithFormat(path.basename(relPath), format, src.isSvg))
+    await writeScaled(src, outPath, targetWidth, targetHeight, format, quality)
+    written.push(outPath)
+  }
+  return written
+}
+
+/**
+ * Scale a source image into all iPhone scale variants.
+ *
+ * @param {string} sourceFile - Absolute path to source image
+ * @param {string} relPath - Path inside the source root (e.g. 'buttons/btn.png')
+ * @param {string} iphoneBaseDir - e.g. <project>/app/assets/iphone/images
+ * @param {Object} opts - Same shape as genAndroidScales
+ * @returns {Promise<string[]>} Paths written
+ */
+export async function genIphoneScales(sourceFile, relPath, iphoneBaseDir, opts = {}) {
+  const { format = null, quality = 85 } = opts
+  const src = await readSource(sourceFile)
+  const written = []
+
+  const parsed = path.parse(relPath)
+  const outDir = path.join(iphoneBaseDir, parsed.dir)
+  fs.mkdirSync(outDir, { recursive: true })
+
+  for (const { suffix, factor } of IPHONE_SCALES) {
+    const targetWidth = Math.max(1, Math.round(src.meta.width * factor))
+    const targetHeight = Math.max(1, Math.round(src.meta.height * factor))
+
+    // SVG sources can't be written as SVG by Sharp — fall back to PNG if the
+    // user didn't specify an explicit output format.
+    const ext = format ? `.${format}` : (src.isSvg ? '.png' : parsed.ext)
+    const outName = `${parsed.name}${suffix}${ext}`
+    const outPath = path.join(outDir, outName)
+
+    await writeScaled(src, outPath, targetWidth, targetHeight, format, quality)
+    written.push(outPath)
+  }
+  return written
+}
+
+function renameWithFormat(filename, format, isSvg = false) {
+  if (format) {
+    const parsed = path.parse(filename)
+    return `${parsed.name}.${format}`
+  }
+  // SVG masters can't be written back as SVG by Sharp — coerce to PNG.
+  if (isSvg) {
+    const parsed = path.parse(filename)
+    return `${parsed.name}.png`
+  }
+  return filename
+}
+
+async function writeScaled(src, outPath, width, height, format, quality) {
+  const targetMax = Math.max(width, height)
+  let pipeline = buildScalePipeline(src, targetMax).resize({
+    width,
+    height,
+    fit: 'contain',
+    background: { r: 0, g: 0, b: 0, alpha: 0 }
+  })
+
+  // For SVG sources without an explicit format, coerce output to PNG
+  // (Sharp cannot write SVG).
+  const fallbackExt = src.isSvg ? 'png' : path.extname(src.path).slice(1).toLowerCase()
+  const fmt = format || fallbackExt
+  pipeline = applyFormat(pipeline, fmt === 'jpg' ? 'jpeg' : fmt, quality)
+
+  await pipeline.toFile(outPath)
+}
+
+function applyFormat(pipeline, format, quality) {
+  switch (format) {
+    case 'png':  return pipeline.png({ quality, compressionLevel: 9 })
+    case 'webp': return pipeline.webp({ quality })
+    case 'avif': return pipeline.avif({ quality })
+    case 'tiff': return pipeline.tiff({ quality, compression: 'lzw' })
+    case 'gif':  return pipeline.gif()
+    case 'jpeg': return pipeline.flatten({ background: '#ffffff' }).jpeg({ quality })
+    default:     return pipeline
+  }
+}

package/src/core/images/index.js

@@ -0,0 +1,171 @@
+/**
+ * PurgeTSS - Images pipeline orchestrator
+ *
+ * Discovers source images (auto from `purgetss/images/` or from a user-provided
+ * path) and generates Titanium multi-density variants for Alloy or Classic
+ * projects.
+ *
+ * Layouts:
+ *   Alloy:   app/assets/android/images/res-{density}/  +  app/assets/iphone/images/
+ *   Classic: Resources/android/images/res-{density}/   +  Resources/iphone/images/
+ *
+ * Subdirectories of `purgetss/images/` are preserved in the output paths.
+ *
+ * @fileoverview Orchestrator for `purgetss images`
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { logger } from '../branding/branding-logger.js'
+import { logger as mainLogger } from '../../shared/logger.js'
+import { confirmWithAlways } from '../../shared/prompt.js'
+import { setConfigProperty } from '../../shared/config-writer.js'
+import { detectProjectType } from '../branding/tiapp-reader.js'
+import { genAndroidScales, genIphoneScales } from './gen-scales.js'
+import { projectsPurge_TSS_Images_Folder } from '../../shared/constants.js'
+
+const SUPPORTED_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.svg'])
+
+export async function runImages(opts) {
+  const {
+    source,             // resolved absolute path (file or directory)
+    projectRoot = process.cwd(),
+    androidOnly = false,
+    iphoneOnly = false,
+    format = null,
+    quality = 85,
+    dryRun = false,
+    yes = false,
+    confirmOverwrites = true
+  } = opts
+
+  if (!fs.existsSync(source)) {
+    throw new Error(`Source not found: ${source}`)
+  }
+
+  const projectType = detectProjectType(projectRoot)
+  const { androidBaseDir, iphoneBaseDir } = resolveOutputDirs(projectRoot, projectType)
+
+  const files = collectImageFiles(source)
+
+  console.log()
+  mainLogger.info('Generating multi-density image variants...')
+  console.log()
+  logger.property('Project:    ', `${projectRoot} (${projectType})`)
+  logger.property('Source:     ', source)
+  logger.property('Images:     ', `${files.length} file${files.length === 1 ? '' : 's'}`)
+  const platforms = []
+  if (!iphoneOnly) platforms.push('Android (5 densities)')
+  if (!androidOnly) platforms.push('iPhone (@1x, @2x, @3x)')
+  logger.property('Platforms:  ', platforms.join(' + '))
+  if (format) logger.property('Format:     ', `convert all to ${format}`)
+  if (dryRun) logger.warning('DRY RUN — no files will be written')
+
+  if (files.length === 0) {
+    logger.warning('No images found. Put your source files inside purgetss/images/ (svg, png, jpg, jpeg, webp, gif).')
+    return { written: [] }
+  }
+
+  if (!dryRun && confirmOverwrites) {
+    logger.warning(`⚠  Scaled images will OVERWRITE existing variants under ${androidBaseDir} and ${iphoneBaseDir}.`)
+    logger.warning(`   Commit first if you want a rollback.`)
+    const choice = await confirmWithAlways('Continue? [y/N/a]', { yes })
+    if (choice === 'no') {
+      logger.info('Aborted.')
+      // eslint-disable-next-line n/no-process-exit
+      process.exit(0)
+    }
+    if (choice === 'always') {
+      const saved = setConfigProperty('images', 'confirmOverwrites', false)
+      if (saved) {
+        logger.success('Saved images.confirmOverwrites = false to purgetss/config.cjs — you won\'t be asked again.')
+      } else {
+        logger.warning('Could not persist preference (config.cjs missing or unreadable). Proceeding anyway.')
+      }
+    }
+  }
+
+  if (projectType === 'unknown') {
+    logger.warning(`Could not detect project layout. Expected 'app/' (Alloy) or 'Resources/' (Classic).`)
+    logger.warning(`Assets will still be written to the detected default paths — verify the output.`)
+  }
+
+  // Relative paths preserve the user's subdirectory structure inside purgetss/images/.
+  // If the source is inside purgetss/images/, compute relPath from that folder
+  // so subdirectories are always preserved in the output — regardless of whether
+  // the user passed the full folder, a subfolder, or a single file.
+  const imagesFolder = projectRoot === process.cwd()
+    ? projectsPurge_TSS_Images_Folder
+    : path.join(projectRoot, 'purgetss', 'images')
+  const sourceIsInsideImagesFolder = source === imagesFolder
+    || source.startsWith(imagesFolder + path.sep)
+
+  const sourceRoot = sourceIsInsideImagesFolder
+    ? imagesFolder
+    : (fs.statSync(source).isDirectory() ? source : path.dirname(source))
+
+  const written = []
+
+  logger.section('Scaling')
+  for (const file of files) {
+    const relPath = path.relative(sourceRoot, file)
+    logger.bullet(relPath)
+
+    if (dryRun) continue
+
+    if (!iphoneOnly) {
+      const androidFiles = await genAndroidScales(file, relPath, androidBaseDir, { format, quality })
+      written.push(...androidFiles)
+    }
+    if (!androidOnly) {
+      const iphoneFiles = await genIphoneScales(file, relPath, iphoneBaseDir, { format, quality })
+      written.push(...iphoneFiles)
+    }
+  }
+
+  if (!dryRun) {
+    console.log()
+    logger.success(`${written.length} file${written.length === 1 ? '' : 's'} written.`)
+    logger.property('Android:    ', androidBaseDir)
+    logger.property('iPhone:     ', iphoneBaseDir)
+  }
+
+  return { written }
+}
+
+function resolveOutputDirs(projectRoot, projectType) {
+  if (projectType === 'classic') {
+    return {
+      androidBaseDir: path.join(projectRoot, 'Resources', 'android', 'images'),
+      iphoneBaseDir: path.join(projectRoot, 'Resources', 'iphone', 'images')
+    }
+  }
+  // Alloy (or unknown fallback uses Alloy convention)
+  return {
+    androidBaseDir: path.join(projectRoot, 'app', 'assets', 'android', 'images'),
+    iphoneBaseDir: path.join(projectRoot, 'app', 'assets', 'iphone', 'images')
+  }
+}
+
+function collectImageFiles(source) {
+  const stat = fs.statSync(source)
+  if (stat.isFile()) {
+    return SUPPORTED_EXTS.has(path.extname(source).toLowerCase()) ? [source] : []
+  }
+  // Directory — recurse
+  return walk(source)
+}
+
+function walk(dir) {
+  const out = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      out.push(...walk(full))
+    } else if (entry.isFile() && SUPPORTED_EXTS.has(path.extname(entry.name).toLowerCase())) {
+      out.push(full)
+    }
+  }
+  return out
+}

package/src/shared/config-manager.js

@@ -16,6 +16,9 @@ import defaultTheme from 'tailwindcss/defaultTheme.js'
 import {
   projectsConfigJS,
   projectsPurgeTSSFolder,
+  projectsPurge_TSS_Fonts_Folder,
+  projectsPurge_TSS_Brand_Folder,
+  projectsPurge_TSS_Images_Folder,
   srcConfigFile
 } from './constants.js'
 import { logger } from './logger.js'
@@ -24,6 +27,29 @@ import { makeSureFolderExists } from './utils.js'
 // Create require for ESM compatibility
 const require = createRequire(import.meta.url)
 
+/**
+ * Parse a padding value from either a number or a percentage string.
+ *
+ *   20     → 20
+ *   '20'   → 20
+ *   '20%'  → 20
+ *
+ * Used for `brand.padding` and `brand.iosPadding` so users can write
+ * self-documenting values like `padding: '25%'` in their config.
+ *
+ * @param {number|string} value
+ * @param {string} fieldName - Config path for error messages (e.g. 'brand.padding')
+ * @returns {number} Integer 0-40
+ */
+function parsePadding(value, fieldName) {
+  if (typeof value === 'number') return value
+  if (typeof value === 'string') {
+    const match = value.trim().match(/^(\d+)%?$/)
+    if (match) return parseInt(match[1], 10)
+  }
+  throw new Error(`Invalid ${fieldName}: expected number or '<N>%' string, got ${JSON.stringify(value)}`)
+}
+
 /**
  * Ensure config file exists - SIMPLE logic
  * 1. If config.cjs exists → use it
@@ -31,6 +57,14 @@ const require = createRequire(import.meta.url)
  * 3. If nothing exists → create config.cjs
  */
 export function ensureConfig() {
+  // Ensure the full purgetss/ subfolder layout exists on every init — keeps
+  // fonts/, brand/, and images/ discoverable from day one instead of
+  // appearing lazily on first use of their respective commands.
+  makeSureFolderExists(projectsPurgeTSSFolder)
+  makeSureFolderExists(projectsPurge_TSS_Fonts_Folder)
+  makeSureFolderExists(projectsPurge_TSS_Brand_Folder)
+  makeSureFolderExists(projectsPurge_TSS_Images_Folder)
+
   // 1. ¿Existe config.cjs? → Úsalo
   if (fs.existsSync(projectsConfigJS)) {
     return
@@ -93,6 +127,18 @@ export function getConfigFile() {
   configFile.purge.options.safelist = configFile.purge.options.safelist ?? []
   configFile.purge.options.plugins = configFile.purge.options.plugins ?? []
 
+  configFile.brand = configFile.brand ?? {}
+  configFile.brand.bgColor = configFile.brand.bgColor ?? '#FFFFFF'
+  configFile.brand.padding = parsePadding(configFile.brand.padding ?? 15, 'brand.padding')
+  configFile.brand.iosPadding = parsePadding(configFile.brand.iosPadding ?? 4, 'brand.iosPadding')
+  configFile.brand.darkBgColor = configFile.brand.darkBgColor ?? null
+  configFile.brand.notification = configFile.brand.notification ?? false
+  configFile.brand.splash = configFile.brand.splash ?? false
+
+  configFile.images = configFile.images ?? {}
+  configFile.images.quality = configFile.images.quality ?? 85
+  configFile.images.format = configFile.images.format ?? null
+
   configFile.theme = configFile.theme ?? {}
   configFile.theme.extend = configFile.theme.extend ?? {}
 

package/src/shared/config-writer.js

@@ -0,0 +1,84 @@
+/**
+ * PurgeTSS - config.cjs patcher
+ *
+ * Small helper for writing a single property into an existing top-level
+ * section (e.g. `brand: { ... }` or `images: { ... }`) of the user's
+ * purgetss/config.cjs. Used by the interactive "always" confirmation option
+ * to persist the user's preference.
+ *
+ * Deliberately narrow: only touches the target property, preserves the
+ * user's indentation style, and leaves every other line byte-identical.
+ * If the target section or key can't be located safely, it no-ops rather
+ * than risking a corrupted config — the caller falls back to the one-shot
+ * `--yes` / PURGETSS_YES behavior.
+ *
+ * @fileoverview Non-destructive single-property writer for config.cjs
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import { projectsConfigJS } from './constants.js'
+
+/**
+ * Set `section.key = value` inside the user's purgetss/config.cjs, preserving
+ * the rest of the file. If the key already exists in that section, its value
+ * is replaced in place; otherwise a new line is appended before the section's
+ * closing brace.
+ *
+ * @param {string} section - Top-level section name (e.g. 'brand', 'images').
+ * @param {string} key - Property key to set inside the section.
+ * @param {*} value - JSON-serializable value (booleans, numbers, strings, null).
+ * @returns {boolean} True on success; false if config is missing or the
+ *   section couldn't be located.
+ */
+export function setConfigProperty(section, key, value) {
+  if (!fs.existsSync(projectsConfigJS)) return false
+
+  const original = fs.readFileSync(projectsConfigJS, 'utf8')
+
+  // Capture the entire section: `<indent>section: { <body> \n<closeIndent>}`.
+  // Non-greedy body match keeps us from swallowing sibling sections.
+  const sectionRegex = new RegExp(
+    `^(\\s*)${section}\\s*:\\s*\\{([\\s\\S]*?)\\n(\\s*)\\}`,
+    'm'
+  )
+  const match = original.match(sectionRegex)
+  if (!match) return false
+
+  const [wholeMatch, sectionIndent, body, closeIndent] = match
+  const propIndent = closeIndent + '  '
+  const valueLiteral = JSON.stringify(value)
+
+  // If the key already exists inside the body, replace its value in place.
+  // Preserves any trailing comment on the same line.
+  const keyRegex = new RegExp(`(\\n\\s+${key}\\s*:\\s*)([^,\\n]+?)(\\s*(?:,|(?=\\n|$)))`)
+  if (keyRegex.test(body)) {
+    const newBody = body.replace(keyRegex, `$1${valueLiteral}$3`)
+    const replaced = `${sectionIndent}${section}: {${newBody}\n${closeIndent}}`
+    fs.writeFileSync(projectsConfigJS, original.replace(wholeMatch, replaced), 'utf8')
+    return true
+  }
+
+  // Key missing — append a new line before the closing brace. Ensure the
+  // previous property line has a trailing comma so the appended property
+  // parses. If that line ends in a // comment, the comma goes between the
+  // value and the comment (not after it).
+  const lines = body.replace(/\s+$/, '').split('\n')
+  const lastIdx = lines.length - 1
+  const lastLine = lines[lastIdx]
+  const commentMatch = lastLine.match(/^(.*?)(\s*\/\/.*)$/)
+  const valuePart = (commentMatch ? commentMatch[1] : lastLine).replace(/\s+$/, '')
+  const commentPart = commentMatch ? commentMatch[2] : ''
+  const needsComma =
+    valuePart &&
+    !valuePart.endsWith(',') &&
+    !valuePart.endsWith('{')
+  lines[lastIdx] = (needsComma ? valuePart + ',' : valuePart) + commentPart
+
+  let newBody = lines.join('\n')
+  newBody += `\n${propIndent}${key}: ${valueLiteral}`
+
+  const replaced = `${sectionIndent}${section}: {${newBody}\n${closeIndent}}`
+  fs.writeFileSync(projectsConfigJS, original.replace(wholeMatch, replaced), 'utf8')
+  return true
+}