purgetss 7.5.3 → 7.6.1

package/src/cli/commands/shades.js

@@ -15,7 +15,7 @@ import fs from 'fs'
 import chalk from 'chalk'
 import { createRequire } from 'module'
 import { alloyProject, makeSureFolderExists } from '../../shared/utils.js'
-import { projectsConfigJS, projectsLibFolder } from '../../shared/constants.js'
+import { projectsConfigJS, projectsLibFolder, projectsSemanticColorsJSON } from '../../shared/constants.js'
 import { logger } from '../../shared/logger.js'
 import { ensureConfig, getConfigFile } from '../../shared/config-manager.js'
 import { cleanDoubleQuotes } from '../utils/file-operations.js'
@@ -67,6 +67,27 @@ export function checkIfColorModule() {
   }
 }
 
+/**
+ * Build the "missing hex" error message shown when the user invokes `shades`
+ * or `semantic` without a hex argument and without `--random`. The common
+ * cause is an unquoted `#` on the command line — bash/zsh treat everything
+ * from `#` onward as a comment, so `pt shades #6A2489` reaches the CLI as
+ * `pt shades` with no argument. We surface the shell behavior explicitly so
+ * the user isn't mystified by a silent random color.
+ */
+export function missingHexMessage(commandName) {
+  return [
+    chalk.red('No hex color provided.'),
+    `If you typed ${chalk.yellow(`pt ${commandName} #6A2489`)} (unquoted), your shell stripped ${chalk.yellow('#6A2489')}`,
+    'as a comment — the CLI never received it.',
+    '',
+    'Try one of these instead:',
+    `  ${chalk.green(`pt ${commandName} '#6A2489'`)}   ${chalk.gray('(quoted)')}`,
+    `  ${chalk.green(`pt ${commandName} 6A2489`)}      ${chalk.gray('(no hash)')}`,
+    `  ${chalk.green(`pt ${commandName} --random`)}    ${chalk.gray('(random color)')}`
+  ]
+}
+
 /**
  * Main shades command - generates color shades from hex codes
  * Maintains exact same logic as original shades() function
@@ -86,11 +107,16 @@ export function checkIfColorModule() {
  * @returns {Promise<boolean>} Success status
  */
 export async function shades(args, options) {
+  if (!args.hexcode && !options.random) {
+    logger.block(...missingHexMessage('shades'))
+    return false
+  }
+
   const chroma = (await import('chroma-js')).default
   const referenceColorFamilies = (await import('../../../lib/color-shades/tailwindColors.js')).default
   const generateColorShades = (await import('../../../lib/color-shades/generateColorShades.js')).default
 
-  const colorFamily = (options.random || !args.hexcode)
+  const colorFamily = options.random
     ? generateColorShades(chroma.random(), referenceColorFamilies)
     : generateColorShades(args.hexcode, referenceColorFamilies)
 
@@ -99,19 +125,14 @@ export async function shades(args, options) {
 
   colorFamily.name = colorFamily.name.replace(/'/g, '').replace(/\//g, '').replace(/\s+/g, ' ')
 
-  const colorObject = createColorObject(colorFamily, colorFamily.hexcode, options)
-
   const silent = options.tailwind || options.json || options.log
+  const inAlloyProject = !silent && alloyProject(silent)
 
-  // Ensure config migration happens before getting config file
-  if (alloyProject(silent) && !silent) {
-    ensureConfig()
-  }
-
-  // Get config file (after potential migration)
-  const configFile = getConfigFile()
+  const colorObject = createColorObject(colorFamily, colorFamily.hexcode, options)
 
-  if (alloyProject(silent) && !silent) {
+  if (inAlloyProject) {
+    ensureConfig()
+    const configFile = getConfigFile()
 
     if (options.override) {
       if (!configFile.theme.colors) configFile.theme.colors = {}
@@ -180,11 +201,309 @@ function createColorObject(family, hexcode, options) {
   return colors
 }
 
+/**
+ * Convert a kebab-case color name to camelCase for semantic JSON keys.
+ * Example: 'amazon-green' → 'amazonGreen'. Leaves single-word names untouched.
+ * Exported because the `semantic` command imports it for shade-conflict detection.
+ *
+ * @param {string} kebabName - kebab-case color name
+ * @returns {string} camelCase name
+ */
+export function toCamelCase(kebabName) {
+  return kebabName.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase())
+}
+
+/**
+ * Validate and normalize the --alpha CLI input.
+ * Returns undefined when no alpha was supplied; throws on invalid input.
+ * Per the Titanium semantic.colors.json spec, alpha is a string in 0.0-100.0
+ * (integer or float). See ti-expert/references/theming.md.
+ *
+ * @param {string|number|undefined} input - raw CLI value
+ * @returns {string|undefined} normalized alpha as string, or undefined
+ */
+export function normalizeAlpha(input) {
+  if (input === undefined || input === null || input === '') return undefined
+  const n = Number(input)
+  if (!Number.isFinite(n) || n < 0 || n > 100) {
+    throw new Error(`--alpha must be a number between 0 and 100 (got "${input}")`)
+  }
+  return String(n)
+}
+
+/**
+ * Wrap a hex value in the Titanium semantic-color extended form when alpha is
+ * present, or return the bare hex string otherwise. Both forms are valid per
+ * the Titanium spec (a single semantic.colors.json may mix them).
+ *
+ * @param {string} hex - hex color
+ * @param {string|undefined} alpha - normalized alpha string, or undefined
+ * @returns {string|{color: string, alpha: string}}
+ */
+function wrapValue(hex, alpha) {
+  return alpha === undefined ? hex : { color: hex, alpha }
+}
+
+export const SHADE_NUMBERS = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950']
+const SHADE_SUFFIX_RE = new RegExp(`^(.+?)(${SHADE_NUMBERS.join('|')})$`)
+
+/**
+ * Detect when a name like 'amazon50' refers to an existing palette shade.
+ * The `semantic --single` command uses this to decide between in-place update
+ * (when the name matches a shade of a palette already declared in config) and
+ * the normal full write flow (when the name is independent). Returns the
+ * conflict descriptor (parentName + shadeNum + camelKey) or null.
+ *
+ * Checks BOTH the kebab and camel forms — kebab matches config.cjs keys,
+ * camel matches semantic.colors.json keys for multi-word families like
+ * `amazonGreen500`.
+ *
+ * @param {Object} configFile - parsed purgetss/config.cjs
+ * @param {string} kebabName - kebab-case name (config.cjs key style)
+ * @param {string} camelName - camelCase name (semantic.colors.json key style)
+ * @returns {{ parentName: string, shadeNum: string, camelKey: string }|null}
+ */
+export function detectFamilyShadeConflict(configFile, kebabName, camelName) {
+  for (const candidate of [kebabName, camelName]) {
+    const match = candidate.match(SHADE_SUFFIX_RE)
+    if (!match) continue
+    const [, parentName, shadeNum] = match
+
+    const extend = configFile?.theme?.extend?.colors?.[parentName]
+    const main = configFile?.theme?.colors?.[parentName]
+    const parentMapping = extend ?? main
+
+    if (parentMapping && typeof parentMapping === 'object' && parentMapping[shadeNum] !== undefined) {
+      return { parentName, shadeNum, camelKey: candidate === kebabName ? camelName : candidate }
+    }
+  }
+  return null
+}
+
+/**
+ * Remove all keys in `existing` that belong to the named semantic family —
+ * the bare camelName (single form) plus camelName + each of the 11 shade
+ * numbers (palette form). Keys outside the family are left untouched, so
+ * unrelated palettes and manually-defined entries (`surfaceColor`, etc.)
+ * survive a re-run. This makes `shades --semantic` consistent with the
+ * non-semantic flow: regenerating a family fully replaces it.
+ *
+ * @param {Object} existing - parsed semantic.colors.json
+ * @param {string} camelName - camelCase family name (e.g., 'amazon', 'glassSurface')
+ * @returns {Object} new object without the family's keys
+ */
+export function stripFamilyKeys(existing, camelName) {
+  const familyKeys = new Set([camelName, ...SHADE_NUMBERS.map(n => `${camelName}${n}`)])
+  const cleaned = {}
+  for (const [key, value] of Object.entries(existing)) {
+    if (!familyKeys.has(key)) cleaned[key] = value
+  }
+  return cleaned
+}
+
+/**
+ * Build a semantic palette with mirror-by-index light/dark inversion,
+ * anchored at shade 500. Pure function — no I/O.
+ *
+ * For each slot at index i in the sorted (50→950) shade list:
+ *   light = shade[last - i].hexcode  (inverted)
+ *   dark  = shade[i].hexcode          (original)
+ * Slot 500 is the anchor (same light/dark).
+ *
+ * When alpha is provided, every value is wrapped as { color, alpha }.
+ *
+ * @param {Object} family - Color family from generateColorShades()
+ * @param {string} kebabName - Normalized color name (e.g., 'amazon-green')
+ * @param {string|undefined} alpha - Optional alpha string (0-100)
+ * @returns {{ semanticEntries: Object, configMapping: Object }}
+ */
+export function buildSemanticPalette(family, kebabName, alpha) {
+  const camelName = toCamelCase(kebabName)
+  const sorted = [...family.shades].sort((a, b) => a.number - b.number)
+  const semanticEntries = {}
+  const configMapping = {}
+
+  sorted.forEach((shade, i) => {
+    const mirror = sorted[sorted.length - 1 - i]
+    const key = `${camelName}${shade.number}`
+    semanticEntries[key] = {
+      light: wrapValue(mirror.hexcode, alpha),
+      dark: wrapValue(shade.hexcode, alpha)
+    }
+    configMapping[shade.number] = key
+  })
+
+  return { semanticEntries, configMapping }
+}
+
+/**
+ * Build a single-entry purpose-based semantic color from explicit per-mode
+ * hex values. Used by `pt semantic --single`. Light and dark are independent;
+ * if `darkHex` is omitted the same value is used for both modes (useful for
+ * overlays/glass surfaces where alpha is the variation, not hue).
+ *
+ * The JSON key is taken VERBATIM — caller is responsible for passing the exact
+ * camelCase form expected in semantic.colors.json (e.g. 'surfaceColor'), since
+ * Titanium's conventions are case-sensitive and the design-layer class name
+ * (config.cjs) is a separate decision that the caller owns.
+ *
+ * @param {string} camelKey - exact JSON key (e.g. 'surfaceColor', 'overlay')
+ * @param {string} lightHex - hex for light mode (required)
+ * @param {string|undefined} darkHex - hex for dark mode (defaults to lightHex)
+ * @param {string|undefined} alpha - normalized alpha string (0-100), wraps both modes
+ * @returns {{ semanticEntries: Object }}
+ */
+export function buildSingleSemantic(camelKey, lightHex, darkHex, alpha) {
+  const dark = darkHex ?? lightHex
+  return {
+    semanticEntries: {
+      [camelKey]: {
+        light: wrapValue(lightHex, alpha),
+        dark: wrapValue(dark, alpha)
+      }
+    }
+  }
+}
+
+/**
+ * Wrap a hex value with optional alpha — exposed so the `semantic` command
+ * can format individual entries without re-importing the building blocks.
+ *
+ * @param {string} hex
+ * @param {string|undefined} alpha
+ * @returns {string|{color:string,alpha:string}}
+ */
+export function wrapHexWithAlpha(hex, alpha) {
+  return wrapValue(hex, alpha)
+}
+
+/**
+ * Read + parse semantic.colors.json if present. Returns {} for missing/empty.
+ * Rethrows on invalid JSON after logging, to protect user data.
+ */
+function readSemanticJSON() {
+  if (!fs.existsSync(projectsSemanticColorsJSON)) return {}
+  const raw = fs.readFileSync(projectsSemanticColorsJSON, 'utf8')
+  if (!raw.trim()) return {}
+  try {
+    return JSON.parse(raw)
+  } catch (err) {
+    logger.info(`${chalk.red('Warning:')} ${chalk.yellow('app/assets/semantic.colors.json')} is not valid JSON. Aborting to avoid data loss.`)
+    throw err
+  }
+}
+
+/**
+ * Write the semantic-colors JSON (caller provides the fully-merged object).
+ * Ensures app/assets/ exists first.
+ */
+function persistSemanticJSON(data) {
+  const assetsFolder = projectsSemanticColorsJSON.replace(/\/semantic\.colors\.json$/, '')
+  makeSureFolderExists(assetsFolder)
+  fs.writeFileSync(projectsSemanticColorsJSON, JSON.stringify(data, null, 2) + '\n', 'utf8')
+}
+
+/**
+ * Write new entries into semantic.colors.json, replacing any prior keys that
+ * belong to the same camelName family (single form + 11 shade form). Unrelated
+ * keys survive untouched. Used by both palette and single-mode fresh writes.
+ *
+ * @param {Object} semanticEntries - new entries to merge in
+ * @param {string} camelName - family name (for stripping)
+ */
+export function writeSemanticJSON(semanticEntries, camelName) {
+  const existing = readSemanticJSON()
+  const cleaned = stripFamilyKeys(existing, camelName)
+  const merged = { ...cleaned, ...semanticEntries }
+  persistSemanticJSON(merged)
+}
+
+/**
+ * Update one entry in semantic.colors.json in place, preserving the existing
+ * key order. Used when `pt semantic --single` is invoked with a name that
+ * matches an existing palette shade — the user is editing a shade value, not
+ * creating a new top-level color, so we must NOT touch config.cjs (the
+ * palette already maps to this key) and we must NOT shift the key to the end.
+ *
+ * Spread-merge with an existing key updates the value while keeping the
+ * original insertion position (V8/spec object key ordering).
+ *
+ * @param {string} camelKey - the JSON key to update (already camelCase)
+ * @param {string|{color:string,alpha:string}} value - new value (bare hex or wrapped form)
+ */
+export function updateSemanticEntry(camelKey, value) {
+  const existing = readSemanticJSON()
+  const updated = { ...existing, [camelKey]: value }
+  persistSemanticJSON(updated)
+}
+
+/**
+ * Write the family-name → configMapping entry into purgetss/config.cjs under
+ * theme.extend.colors (or theme.colors when --override is set). Cleans up the
+ * opposite branch so the mapping doesn't duplicate.
+ *
+ * @param {string} kebabName - key in theme.extend.colors / theme.colors
+ * @param {Object|string} configMapping - palette object or single string
+ * @param {Object} options - CLI options (reads .override and .quotes)
+ */
+export function writeConfigMapping(kebabName, configMapping, options) {
+  const configFile = getConfigFile()
+
+  if (options.override) {
+    if (!configFile.theme.colors) configFile.theme.colors = {}
+    configFile.theme.colors[kebabName] = configMapping
+
+    if (configFile.theme.extend.colors) {
+      if (configFile.theme.extend.colors[kebabName]) delete configFile.theme.extend.colors[kebabName]
+      if (Object.keys(configFile.theme.extend.colors).length === 0) delete configFile.theme.extend.colors
+    }
+  } else {
+    if (!configFile.theme.extend.colors) configFile.theme.extend.colors = {}
+    configFile.theme.extend.colors[kebabName] = configMapping
+
+    if (configFile.theme.colors) {
+      if (configFile.theme.colors[kebabName]) delete configFile.theme.colors[kebabName]
+      if (Object.keys(configFile.theme.colors).length === 0) delete configFile.theme.colors
+    }
+  }
+
+  fs.writeFileSync(projectsConfigJS, 'module.exports = ' + cleanDoubleQuotes(configFile, options), 'utf8', err => { throw err })
+  checkIfColorModule()
+}
+
+/**
+ * Combined write for palette mode (JSON entries + config mapping in one call).
+ * Single mode uses writeSemanticJSON alone — class naming is a design-layer
+ * decision that belongs to the user, not auto-derived from the semantic key.
+ *
+ * @param {Object} semanticEntries - Output of buildSemanticPalette().semanticEntries
+ * @param {string} kebabName - Color family name as config.cjs key
+ * @param {Object} configMapping - palette's 11-shade mapping
+ * @param {Object} options - CLI options (reads .override and .quotes)
+ */
+export function writeSemanticColors(semanticEntries, kebabName, configMapping, options) {
+  const camelName = toCamelCase(kebabName)
+  writeSemanticJSON(semanticEntries, camelName)
+  writeConfigMapping(kebabName, configMapping, options)
+}
+
 /**
  * Export for CLI usage
  */
 export default {
   colorModule,
   checkIfColorModule,
-  shades
+  shades,
+  missingHexMessage,
+  toCamelCase,
+  buildSemanticPalette,
+  buildSingleSemantic,
+  detectFamilyShadeConflict,
+  updateSemanticEntry,
+  writeSemanticJSON,
+  writeConfigMapping,
+  wrapHexWithAlpha,
+  normalizeAlpha,
+  stripFamilyKeys,
+  writeSemanticColors
 }

package/src/cli/utils/project-detection.js

@@ -64,8 +64,10 @@ export function validateProject(silent = false) {
 
   if (projectType === 'unknown') {
     if (!silent) {
-      logger.info('Please make sure you are running purgetss within an Alloy or Classic Project.')
-      logger.info('For more information, visit https://purgetss.com')
+      logger.block(
+        'Please make sure you are running purgetss within an Alloy or Classic Project.',
+        'For more information, visit https://purgetss.com'
+      )
     }
     return false
   }

package/src/core/analyzers/class-extractor.js

@@ -14,6 +14,7 @@ import _ from 'lodash'
 import chalk from 'chalk'
 import convert from 'xml-js'
 import traverse from 'traverse'
+import * as acorn from 'acorn'
 
 /**
  * Get unique classes from all XML and controller files - COPIED exactly from original getUniqueClasses() function
@@ -98,7 +99,7 @@ export function extractClassesOnly(currentText, currentFile) {
  * @param {string} line - Line of code from controller file
  * @returns {Array} Array of class names found in line
  */
-function extractWordsFromLine(line) {
+function extractWordsFromLineRegex(line) {
   const patterns = [
     {
       // apply: 'classes'
@@ -155,12 +156,12 @@ function extractWordsFromLine(line) {
  * @param {string} data - Controller file content
  * @returns {Array} Array of class names found in controller
  */
-function processControllers(data) {
+function processControllersRegex(data) {
   const allWords = []
   const lines = data.split(/\r?\n/)
 
   lines.forEach(line => {
-    const words = extractWordsFromLine(line)
+    const words = extractWordsFromLineRegex(line)
     if (words.length > 0) {
       allWords.push(...words)
     }
@@ -169,6 +170,112 @@ function processControllers(data) {
   return allWords
 }
 
+const AST_META_KEYS = new Set(['type', 'loc', 'range', 'start', 'end', 'sourceType', 'comments'])
+
+function collectLiterals(node, out) {
+  if (!node || typeof node !== 'object' || !node.type) return
+
+  switch (node.type) {
+    case 'Literal':
+      if (typeof node.value === 'string') {
+        node.value.split(/\s+/).forEach(token => { if (token) out.push(token) })
+      }
+      return
+
+    case 'TemplateLiteral':
+      if (node.expressions.length === 0 && node.quasis.length > 0) {
+        const cooked = node.quasis[0].value.cooked
+        if (typeof cooked === 'string') {
+          cooked.split(/\s+/).forEach(token => { if (token) out.push(token) })
+        }
+      }
+      return
+
+    case 'ArrayExpression':
+      for (const element of node.elements) {
+        if (element && element.type !== 'SpreadElement') collectLiterals(element, out)
+      }
+      return
+
+    case 'ConditionalExpression':
+      collectLiterals(node.consequent, out)
+      collectLiterals(node.alternate, out)
+      return
+
+    default:
+      return
+  }
+}
+
+function walkAST(node, out) {
+  if (!node || typeof node !== 'object') return
+
+  if (Array.isArray(node)) {
+    for (const child of node) walkAST(child, out)
+    return
+  }
+
+  if (!node.type) return
+
+  if (node.type === 'Property' && !node.computed && !node.shorthand && node.key) {
+    const keyName = node.key.type === 'Identifier'
+      ? node.key.name
+      : (node.key.type === 'Literal' ? node.key.value : undefined)
+    if (keyName === 'classes' || keyName === 'apply') {
+      collectLiterals(node.value, out)
+    }
+  }
+
+  if (node.type === 'CallExpression' && node.callee && node.arguments.length >= 2) {
+    const callee = node.callee
+    let match = false
+    if (
+      callee.type === 'MemberExpression' &&
+      !callee.computed &&
+      callee.property &&
+      callee.property.type === 'Identifier' &&
+      /Class$/.test(callee.property.name)
+    ) {
+      match = true
+    } else if (callee.type === 'Identifier' && callee.name === 'resetClass') {
+      match = true
+    }
+    if (match) collectLiterals(node.arguments[1], out)
+  }
+
+  for (const key of Object.keys(node)) {
+    if (AST_META_KEYS.has(key)) continue
+    walkAST(node[key], out)
+  }
+}
+
+/**
+ * Process a controller file's source and return utility classes referenced by
+ * the whitelisted expression shapes (`classes:`, `apply:`, `.xxxClass(target, value)`,
+ * `resetClass(target, value)`). Falls back to the per-line regex scanner when
+ * the parser rejects the source.
+ *
+ * @param {string} data - Controller file content
+ * @returns {Array} Array of class name tokens
+ */
+export function processControllers(data) {
+  try {
+    const ast = acorn.parse(data, {
+      ecmaVersion: 'latest',
+      sourceType: 'script',
+      allowReturnOutsideFunction: true,
+      allowAwaitOutsideFunction: true,
+      allowImportExportEverywhere: true,
+      allowHashBang: true
+    })
+    const out = []
+    walkAST(ast, out)
+    return out
+  } catch {
+    return processControllersRegex(data)
+  }
+}
+
 /**
  * Encode HTML entities - COPIED exactly from original encodeHTML() function
  * NO CHANGES to logic, preserving 100% of original functionality

package/src/core/branding/brand-config.js

@@ -0,0 +1,111 @@
+/**
+ * PurgeTSS - Brand command config resolver
+ *
+ * Merges three sources of configuration, in this precedence order:
+ *   1. CLI flags (highest priority)
+ *   2. `brand: { ... }` section from purgetss/config.cjs
+ *   3. Built-in defaults (lowest priority)
+ *
+ * Also auto-discovers logo images inside `./purgetss/brand/` following the
+ * project convention:
+ *   logo.{svg,png}          → required (main logo)
+ *   logo-mono.{svg,png}     → optional (monochrome layer + notifications)
+ *   logo-dark.{svg,png}     → optional (iOS 18+ dark variant)
+ *   logo-tinted.{svg,png}   → optional (iOS 18+ tinted variant)
+ *
+ * CLI --monochrome-logo / --dark-logo / --tinted-logo always override
+ * discovery, and the positional argument overrides the main logo.
+ *
+ * @fileoverview Brand config + logo discovery
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { getConfigFile } from '../../shared/config-manager.js'
+
+const BRAND_DIR = 'purgetss/brand'
+const SUPPORTED_EXTS = ['svg', 'png']
+
+/**
+ * Find the first existing file matching <baseName>.<ext> for each supported ext.
+ * @param {string} baseDir - Absolute path to the search directory
+ * @param {string} baseName - Filename without extension (e.g. 'logo-mono')
+ * @returns {string|null} Absolute path to the first match, or null
+ */
+function findLogoFile(baseDir, baseName) {
+  for (const ext of SUPPORTED_EXTS) {
+    const candidate = path.join(baseDir, `${baseName}.${ext}`)
+    if (fs.existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+/**
+ * Build the final opts object for runBranding().
+ *
+ * @param {Object} cliOptions - Raw options from Commander
+ * @param {string|undefined} cliLogo - Positional logo arg from Commander
+ * @param {string} projectRoot - Absolute project root
+ * @returns {Object} Resolved options
+ */
+export function resolveBrandConfig(cliOptions, cliLogo, projectRoot) {
+  const brandConfig = loadBrandSection()
+  const brandDir = path.join(projectRoot, BRAND_DIR)
+
+  const resolved = {
+    logo: pickLogo(cliLogo, brandConfig.logo, brandDir, 'logo', projectRoot),
+    monochromeLogo: pickLogo(cliOptions.monochromeLogo, brandConfig.monochromeLogo, brandDir, 'logo-mono', projectRoot),
+    darkLogo: pickLogo(cliOptions.darkLogo, brandConfig.darkLogo, brandDir, 'logo-dark', projectRoot),
+    tintedLogo: pickLogo(cliOptions.tintedLogo, brandConfig.tintedLogo, brandDir, 'logo-tinted', projectRoot),
+
+    bgColor: cliOptions.bgColor ?? brandConfig.bgColor ?? '#FFFFFF',
+    bgColorExplicit: Boolean(cliOptions.bgColor ?? brandConfig.bgColor),
+    darkBgColor: cliOptions.darkBgColor ?? brandConfig.darkBgColor ?? null,
+    padding: cliOptions.padding ?? brandConfig.padding ?? 15,
+    iosPadding: cliOptions.iosPadding ?? brandConfig.iosPadding ?? 4,
+
+    // Kitchen-sink defaults: adaptive + marketplace are always generated; only
+    // notification and splash are opt-in. Config can pre-enable them.
+    notification: Boolean(cliOptions.notification ?? brandConfig.notification ?? false),
+    splash: Boolean(cliOptions.splash ?? brandConfig.splash ?? false),
+
+    withDark: cliOptions.dark !== false && (brandConfig.dark ?? true),
+    withTinted: cliOptions.tinted !== false && (brandConfig.tinted ?? true),
+
+    cleanupLegacy: Boolean(cliOptions.cleanupLegacy),
+    aggressive: Boolean(cliOptions.aggressive),
+    projectRoot,
+    output: cliOptions.output || null,
+    dryRun: Boolean(cliOptions.dryRun),
+    notes: Boolean(cliOptions.notes),
+    confirmOverwrites: brandConfig.confirmOverwrites !== false
+  }
+
+  return resolved
+}
+
+/**
+ * @returns {Object} The `brand` section of the resolved config, or {} if missing/invalid.
+ */
+function loadBrandSection() {
+  try {
+    const cfg = getConfigFile()
+    if (cfg && typeof cfg === 'object' && cfg.brand && typeof cfg.brand === 'object') {
+      return cfg.brand
+    }
+  } catch {
+    // Config file missing or invalid — fall back to empty defaults.
+  }
+  return {}
+}
+
+/**
+ * Resolve a logo path with proper precedence.
+ * Config-relative paths are resolved against projectRoot.
+ */
+function pickLogo(cliValue, configValue, brandDir, baseName, projectRoot) {
+  if (cliValue) return path.resolve(cliValue)
+  if (configValue) return path.isAbsolute(configValue) ? configValue : path.resolve(projectRoot, configValue)
+  return findLogoFile(brandDir, baseName)
+}