theamify-cli 1.0.1 → 2.0.0

package/README.md

@@ -1,7 +1,7 @@
 # 🎨 theamify
 
 > **GRUB Theme Manager & Interactive Browser Wizard**  
-> Browse, **preview (terminal thumbnails)**, download and apply GRUB boot themes — powered by the original `theamify` engine, now on npm as **`theamify-cli`**.
+> Browse, **preview (terminal thumbnails)**, download and apply GRUB boot themes — now on npm as **`theamify-cli`**.
 
 ---
 
@@ -13,42 +13,49 @@
 npm install -g theamify-cli
 ```
 
-The `-g` global flag puts the `theamify` command on your system `PATH` (or provisions a user-local runtime), so you can call it from **any folder and any terminal**:
+The `-g` flag puts the `theamify` command on your system `PATH` (or provisions a user-local runtime under `~/.local/share/theamify`), so you can call it from **any folder and any terminal**:
 
 ```bash
-theamify                    # ✨ interactive theme browser wizard
+theamify                    # ✨ interactive wizard (detects tools → browse → preview → apply)
 theamify list               # list all themes with status
-theamify info <name>        # details + terminal preview (needs chafa)
+theamify info <name>        # details + terminal preview
 theamify get <name>         # download & cache a theme
 sudo theamify use <name>    # apply to GRUB + rebuild
+theamify update             # update tools (chafa, grub-customizer) + re-download themes
 theamify status             # GRUB & dependency status
-theamify doctor             # diagnose install, GRUB & dependencies
-theamify uninstall          # remove theamify (asks before deleting anything)
+theamify doctor             # diagnose install, GRUB, tools & dependencies
+theamify uninstall          # remove only theamify (keeps chafa & grub-customizer)
 ```
 
-> 💡 Already installed? Upgrading is the same command — npm's **global** install fetches the latest release and your downloaded themes & registry edits are preserved:
->
-> ```bash
-> npm install -g theamify-cli@latest
-> ```
-
-> 🧰 Prefer a zero-install run (no permanent install)? Use npx directly:
->
-> ```bash
-> npx -y theamify-cli
-> ```
+> 💡 Upgrading is the same command — `npm install -g theamify-cli@latest`, and your downloaded themes & registry edits are preserved.  
+> 🧰 Zero-install run (no permanent install): `npx -y theamify-cli`
 
 ---
 
-## ✨ What's New in v1.0.0 (npm wizard release)
+## ✨ What's New (v1.1.0 — npm release)
 
 | Feature | Details |
 |---|---|
-| 🧙 **Interactive browser wizard** | `theamify` with no args → a clack-powered picker (mirroring GitSwitch) to **browse → preview → apply** |
-| 🖼️ **Terminal thumbnail preview** | Pick a theme and see its actual boot-screen preview inline via `chafa` before you commit |
-| 📦 **npm global install** | One command, run from anywhere — engine provisions itself under `~/.local/share/theamify` (writable, no sudo needed) |
-| 🩺 **`theamify doctor`** | Diagnose install, GRUB, active theme, registry & dependencies |
-| ⌨️ **Ctrl+C / Ctrl+Z safe** | Terminal signal safety net so interactive `sudo` during `use` is interruptible |
+| 🧙 **Interactive wizard** | One command: detect companion tools → pick theme → **preview** → apply |
+| 🧩 **Auto-detected companion tools** | **chafa** (thumbnails) + **grub-customizer** (GUI) are detected first; installed if missing, or **option to update** if present — then it continues on its own |
+| 🖼️ **Terminal thumbnail preview** | See the boot-screen image inline via `chafa` before you commit |
+| 📦 **npm global install** | Engine provisions itself user-writable (no sudo for downloads) |
+| 🩺 **`theamify doctor`** | Diagnose install, GRUB, active theme, registry, tools & dependencies |
+| 🗑 **Safe uninstall** | Removes **only theamify** — leaves chafa & grub-customizer for later use |
+| ⌨️ **Ctrl+C / Ctrl+Z safe** | Signal safety net; interactive `sudo` is never frozen |
+
+---
+
+## 🧭 Wizard Sequence (every `theamify` run)
+
+1. **Detect companion tools** — `chafa` then `grub-customizer`. For each:  
+   - **Already installed?** → *“Update it now? (or just continue)”* — Continue moves on.  
+   - **Missing?** → *“Install `<name>`? Yes/No”* → installs via your package manager (`sudo`), then continues.  
+2. **Show the theme picker** — every registry theme with status (`[REMOTE]`/`[CACHED]`/`[ACTIVE]`).
+3. **Pick a theme** → optional **terminal thumbnail preview** (needs `chafa`).
+4. **Act** — download, apply to GRUB, or open in browser.
+
+> Companion tools are installed strictly **before** the browser, so previews are ready when you need them.
 
 ---
 
@@ -60,14 +67,35 @@ theamify uninstall          # remove theamify (asks before deleting anything)
 | `git` | Downloading / cloning themes |
 | `curl` **or** `wget` | Downloading |
 | `chafa` | Terminal thumbnail previews — **auto-installed by the wizard** |
-| `sudo` | Only applying a GRUB theme (`theamify use`) |
+| `grub-customizer` | GUI to tweak GRUB menu — **auto-installed by the wizard** |
+| `sudo` | Tool installs + applying a GRUB theme (`theamify use`) |
 
 ---
 
-## Rosetta Stone — classic tool vs npm CLI
+## 📁 Project Structure (npm package)
+
+```
+theamify/
+├── bin/theamify.js         # npm bin entry → src/cli.js
+├── src/
+│   ├── cli.js              # command router + signal safety net
+│   ├── core/engine.js      # runtime provisioning & engine forwarding
+│   ├── commands/manage.js  # doctor / status / uninstall
+│   ├── wizard/browse.js    # interactive wizard (browse → preview → apply)
+│   └── lib/
+│       ├── conf.js         # themes.conf registry parser
+│       └── tools.js        # companion tools: chafa + grub-customizer
+├── vendor/                 # bundled bash engine (theamify + lib/ + config/)
+├── test/                   # unit tests (node:test)
+├── package.json
+└── .github/workflows/     # ci.yml + publish.yml (npm OIDC)
+```
 
-The npm CLI is a thin Node wrapper around the original Bash engine, so every
-non-interactive command still behaves identically:
+---
+
+## Rosetta Stone — CLI vs classic tool
+
+The npm CLI is a thin wrapper around the original Bash engine; every non-interactive command behaves identically:
 
 | npm CLI | Original tool |
 |---|---|
@@ -77,31 +105,24 @@ non-interactive command still behaves identically:
 | `theamify info <n>` | `theamify info <n>` |
 | `theamify add/del/remove/open/update` | same names |
 
-`theamify <no args>` is where the wizard differs — it opens the interactive
-browser/preview/apply flow instead of the flat TUI menu.
+`theamify <no args>` differs — it runs the interactive wizard (tools-then-browser) instead of the flat TUI menu.
 
 ---
 
-## Theme Previews in the Terminal
+## 🧩 Companion Tools: chafa & grub-customizer
 
-chafa is a **first-class dependency of the wizard** — the first step of every
-wizard run ensures it's present (installing it when missing), updates it on
-`theamify update`, and removes it on `theamify uninstall`.
+The wizard manages two companion tools as first-class:
 
-```bash
-theamify            # Step 1: ensures chafa (prompts to install if missing)
-```
+| Tool | Purpose | Install command (apt) | Lifecycle |
+|---|---|---|---|
+| `chafa` | Renders theme thumbnails in the terminal | `sudo apt install chafa` | auto-installed/updated by wizard |
+| `grub-customizer` | GUI for GRUB menu & theme tweaks | `sudo apt install grub-customizer` | auto-installed/updated by wizard |
 
-Or check/install it directly via your package manager:
-```bash
-sudo apt install chafa
-```
-
-```bash
-theamify                                # pick a theme → auto-preview
-theamify info <name>                    # details + thumbnail preview
-theamify update                         # also updates chafa
-```
+**Behavior:**  
+- **Detect** → if present, offer to update; if absent, install (with your consent).  
+- **Continue** regardless of Yes/No — the wizard proceeds to the theme picker.  
+- **`theamify update`** updates tools then re-downloads themes.
+- **`theamify uninstall`** removes **only** theamify — chafa and grub-customizer stay on the system for later use.
 
 ---
 
@@ -120,167 +141,6 @@ theamify update                         # also updates chafa
 
 ---
 
-## 📁 Project Structure (npm package)
-
-```
-bin/theamify.js         # npm bin → src/cli.js
-src/cli.js              # command router + signal safety net
-src/core/engine.js      # runtime provisioning & engine forwarding
-src/lib/conf.js         # themes.conf registry parser
-src/commands/manage.js  # doctor / status / uninstall
-src/wizard/browse.js    # interactive browser + chafa preview + apply
-vendor/                 # bundled bash engine (theamify + lib/ + config/)
-```
-
----
-
-## 🗑 Uninstalling
-
-```bash
-theamify uninstall          # interactive — removes the engine runtime
-npm uninstall -g theamify-cli
-```
-
-Your active GRUB theme and `/etc/default/grub` settings are always preserved.
-
----
-
 ## 📄 License
 
 MIT — see [LICENSE](LICENSE). Don Artkins 2026.
-
-## Project Structure
-```bash
-theamify/
-
-|-- theamify              # Main CLI executable
-
-|-- install.sh            # System-wide installer
-
-|-- uninstall.sh          # Remover
-
-|-- update.sh             # Self-updater (git pull + reinstall)
-
-|-- lib/
-
-|   |-- colors.sh         # ANSI colors & UI components
-
-|   |-- utils.sh          # Helpers, git clone, dep checks
-
-|   |-- grub.sh           # GRUB detection & apply logic
-
-|   `-- themes.sh         # Theme registry CRUD & download
-
-|-- config/
-
-|   `-- themes.conf       # Theme registry database
-
-|-- themes/               # Downloaded theme cache (auto-populated)
-
-|-- .repo_cache/          # Git clone cache (auto-populated)
-
-|-- .gitignore
-
-|-- LICENSE                # MIT
-
-`-- CONTRIBUTING.md
-```
-
-## Install
-
-```bash
-git clone https://github.com/DonArtkins/theamify
-cd theamify
-sudo ./install.sh
-```
-
-After install, `theamify` is available system-wide - run it from any terminal.  
-Only `theamify use` requires `sudo`. All other commands run as a normal user.
-
-### Updating an existing install
-
-`install.sh` deliberately leaves an already-installed `config/themes.conf`
-alone, so your own `add`/`del` edits via `theamify` survive a reinstall.
-That also means a plain `sudo ./install.sh` will **not** pick up registry
-changes from this checkout (new/removed/edited entries) - pass `--sync-conf`
-when you want that:
-
-```bash
-sudo ./install.sh --sync-conf
-```
-
-See [CONTRIBUTING.md](CONTRIBUTING.md#developing-against-an-existing-install)
-for the full dev-vs-installed workflow.
-
-## Usage
-
-```bash
-theamify                    # Interactive TUI menu
-theamify list               # List all themes with status
-theamify info <name>        # Show details + preview (needs chafa)
-theamify get <name>         # Download & cache a theme
-theamify get --all          # Download every theme
-sudo theamify use <name>    # Apply theme to GRUB + rebuild
-theamify update <name>      # Re-download one theme
-theamify update             # Re-download all cached themes
-theamify open <name>        # Open source page in browser
-theamify add <github-url>   # Add new theme to registry
-theamify del <name>         # Remove theme from registry
-theamify remove <name>      # Clear local cache (keeps registry entry)
-theamify status             # Show GRUB + dependency status
-theamify clean               # Clear repo clone cache
-```
-
-## Theme Previews in Terminal
-
-Install `chafa` for inline image previews in `theamify info`:
-
-```bash
-sudo apt install chafa
-```
-
-## Themes Included
-
-| Name             | Style           | Source |
-|------------------|-----------------|--------|
-| CyberEXS         | Cyberpunk dark  | [gnome-look](https://www.gnome-look.org/p/1968990) |
-| CyberSynchro     | Cyberpunk teal  | [gnome-look](https://www.gnome-look.org/p/1972621) |
-| Space-Isolation  | Sci-Fi          | [gnome-look](https://www.gnome-look.org/p/2296342) |
-| Kawaii-GRUB      | Anime           | [gnome-look](https://www.gnome-look.org/p/2218890) |
-| Kayoko-Onikata   | Anime / Cat     | [gnome-look](https://www.gnome-look.org/p/2350900) |
-| Matrices         | Abstract tech   | [gnome-look](https://www.gnome-look.org/p/2271298) |
-| Particle         | Abstract        | [gnome-look](https://www.gnome-look.org/p/2269763) |
-| Zzz-GRUB         | Chill / Cat     | [gnome-look](https://www.gnome-look.org/p/2354136) |
-
-> **Matrices / Particle note:** both repos ship no pre-built theme folder -
-> `backgrounds/`, `common/`, and `config/` are raw assets, and `theme.txt` is
-> only produced at build time by their `generate.sh` (`-t [window|sidebar]
-> -s [1080p|2k|4k]`). The registry entries use a `generate:<args>` SUBDIR so
-> `theamify get` drives that script automatically - see CONTRIBUTING.md for
-> how that mechanism works if you want to add another theme shaped like this.
-
-## Add Your Own Theme
-
-```bash
-theamify add https://github.com/someone/their-grub-theme
-```
-
-Follow the interactive wizard - it asks for name, subdir, description, and tags,
-then appends the entry to `themes.conf`.
-
-## Uninstall
-
-```bash
-sudo ./uninstall.sh
-```
-
-Your active GRUB theme and `/etc/default/grub` settings are preserved.
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, coding conventions, and how
-to submit a theme or a patch.
-
-## License
-
-MIT - see [LICENSE](LICENSE). Don Artkins 2026.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theamify-cli",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "theamify — GRUB theme manager & interactive browser wizard. Browse, preview, download and apply GRUB boot themes from the terminal.",
   "type": "module",
   "main": "src/cli.js",
@@ -49,4 +49,4 @@
     "execa": "^8.0.1",
     "picocolors": "^1.1.1"
   }
-}
+}

package/src/cli.js

@@ -3,7 +3,7 @@ import pc from 'picocolors';
 import { createRequire } from 'node:module';
 import { runThemeBrowser } from './wizard/browse.js';
 import { runDoctor, runStatus, runUninstallWizard } from './commands/manage.js';
-import { updateChafa } from './lib/chafa.js';
+import { updateManagedTools } from './lib/tools.js';
 import { runEngine } from './core/engine.js';
 
 const require = createRequire(import.meta.url);
@@ -85,9 +85,9 @@ const main = defineCommand({
       case 'uninstall':
         return runUninstallWizard();
       case 'update':
-        // Self-update path: refresh the thumbnail renderer, then forward theme
-        // re-downloads to the engine (no name → all cached themes).
-        await updateChafa();
+        // Self-update path: refresh companion tools (chafa, grub-customizer),
+        // then forward theme re-downloads to the engine.
+        await updateManagedTools();
         return forwardEngine(['update', ...rest]);
       case 'use':
       case 'apply':

package/src/commands/manage.js

@@ -2,15 +2,15 @@ import fs from 'node:fs';
 import path from 'node:path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { execa } from 'execa';
+import { execa, execaSync } from 'execa';
 import {
   findInstalledRuntime,
   USER_DIR,
   USER_BIN_LINK,
   resolveEngine,
 } from '../core/engine.js';
-import { parseThemes } from '../lib/conf.js';
-import { uninstallChafa } from '../lib/chafa.js';
+import { parseThemes, resolveConfPath } from '../lib/conf.js';
+import { companionToolStatus } from '../lib/tools.js';
 
 /** `theamify doctor` — installation, GRUB and dependency health. */
 export async function runDoctor() {
@@ -23,29 +23,34 @@ export async function runDoctor() {
 
   // Registry / theme count
   try {
-    const themes = parseThemes();
+    const themes = parseThemes(resolveConfPath());
     const cached = themes.filter((t) => fs.existsSync(path.join(USER_DIR, 'themes', t.name)));
     console.log(`  Registry : ${themes.length} theme(s), ${cached.length} cached`);
   } catch (e) {
     console.log(`  Registry : ${pc.red(`unreadable (${e.message})`)}`);
   }
 
+  // Base dependencies
+  const deps = ['git', 'wget', 'curl'].map((d) => [d, which(d)]);
+  console.log('  Deps     : ' + deps.map(([d, ok]) => `${d}:${ok ? pc.green('✓') : pc.dim('—')}`).join(' '));
+
+  // Companion tools (chafa, grub-customizer)
+  const tools = companionToolStatus();
+  console.log('  Tools    : ' + tools.map((t) => `${t.name}:${t.present ? pc.green('✓') : pc.dim('—')}`).join(' '));
+
   // GRUB active theme + dir
   const grubDir = grubDetectDir();
   console.log(`  GRUB dir : ${pc.cyan(grubDir)}`);
   const active = activeThemeLabel();
   console.log(`  Active   : ${active ? pc.green('⭐ ' + active) : pc.dim('none')}`);
 
-  // Dependencies
-  const deps = ['git', 'chafa', 'wget', 'curl'].map((d) => [d, which(d)]);
-  console.log('  Deps     : ' + deps.map(([d, ok]) => `${d}:${ok ? pc.green('✓') : pc.dim('—')}`).join(' '));
   const grub = ['update-grub', 'grub-mkconfig', 'grub2-mkconfig'].filter((c) => which(c));
   console.log(`  GRUB cmd : ${grub.length ? grub.join(', ') : pc.red('none found')}`);
   console.log();
 }
 
 function which(bin) {
-  try { return execa.sync('which', [bin], { reject: false }).stdout.trim(); } catch { return ''; }
+  try { return execaSync('which', [bin], { reject: false }).stdout.trim(); } catch { return ''; }
 }
 
 function grubDetectDir() {
@@ -113,10 +118,10 @@ export async function runUninstallWizard() {
   });
   if (p.isCancel(keepGrub)) { p.cancel('Aborted.'); process.exit(0); }
 
-  // Optionally remove the thumbnail renderer the wizard installed.
-  await uninstallChafa();
+  // Companion tools (chafa, grub-customizer) are intentionally LEFT in place —
+  // the user may want them for later; uninstall only removes theamify itself.
 
   p.outro(pc.green(
-    `Uninstalled.${removed ? ' Runtime removed.' : ''}${keepGrub ? ' Active GRUB theme left in place.' : ' To revert GRUB, remove GRUB_THEME= from /etc/default/grub and rebuild.'}`,
+    `Uninstalled.${removed ? ' Runtime removed.' : ''}${keepGrub ? ' Active GRUB theme left in place.' : ' To revert GRUB, remove GRUB_THEME= from /etc/default/grub and rebuild.'} Companion tools (chafa, grub-customizer) were kept for your use.`,
   ));
 }

package/src/lib/tools.js

@@ -67,10 +67,121 @@ function packageNameFor(tool, pm) {
 }
 
 /** @returns {boolean} whether the tool binary is on PATH (sync) */
-function hasToolSync(tool) {
+export function hasToolSync(tool) {
   try {
     return Boolean(execaSync('bash', ['-c', `command -v ${tool.bin}`], { reject: false }).stdout.trim());
   } catch {
     return false;
   }
+}
+
+/**
+ * Install a tool via sudo, prompting the user first. Returns true when the tool
+ * is usable afterwards.
+ * @param {{name:string,bin:string,purpose:string,install?:Object}} tool
+ * @param {{silent?:boolean}} [opts]
+ */
+export async function ensureTool(tool, { silent = false } = {}) {
+  if (await hasTool(tool)) return true;
+
+  const pm = detectPackageManager();
+  const pkg = packageNameFor(tool, pm);
+  if (!pm || !pkg) {
+    if (!silent) p.log.warn(`No supported package manager (or no package) found for ${tool.name} — install "${tool.bin}" manually.`);
+    return false;
+  }
+
+  if (!silent) {
+    const want = await p.confirm({
+      message: `Install ${pc.cyan(tool.name)} (${pkg}) for ${tool.purpose}?`,
+      initialValue: true,
+    });
+    if (p.isCancel(want) || !want) {
+      p.log.message(pc.dim(`Skipped ${tool.name} — install later with your package manager.`));
+      return false;
+    }
+  }
+
+  const s = p.spinner();
+  s.start(`Installing ${tool.name}…`);
+  try {
+    // Release the spinner so the sudo prompt is visible & interruptible.
+    s.stop('');
+    const args = pm === 'pacman' ? ['-S', '--noconfirm', pkg] : [pm, 'install', '-y', pkg];
+    await runPrivileged(args);
+    if (!(await hasTool(tool))) throw new Error(`Install appeared to complete, but "${tool.bin}" is not on PATH.`);
+    if (!silent) p.log.success(`${tool.name} installed.`);
+    return true;
+  } catch (e) {
+    if (!silent) p.log.warn(`${tool.name} install failed: ${e.message}`);
+    return false;
+  }
+}
+
+/**
+ * If a tool is present, offer to update it (default: just continue). If missing,
+ * install it. This is the wizard's "auto-detect → install or update → continue".
+ */
+export async function ensureManagedTool(tool) {
+  if (await hasTool(tool)) {
+    const decision = await p.confirm({
+      message: `${pc.cyan(tool.name)} is already installed. Update it now? (or just continue)`,
+      initialValue: false,
+    });
+    if (p.isCancel(decision)) return true;
+    if (decision) return updateTool(tool, { prompt: false });
+    p.log.message(pc.dim(`${tool.name} kept as-is — continuing.`));
+    return true;
+  }
+  return ensureTool(tool, { silent: false });
+}
+
+/** Run the wizard through every companion tool in registry order. */
+export async function ensureManagedTools() {
+  p.note('Companion tools are detected, installed or updated first.', 'Setup');
+  for (const tool of TOOLS) {
+    await ensureManagedTool(tool);
+  }
+}
+
+/** Upgrade all managed companion tools (used by `theamify update`). */
+export async function updateManagedTools() {
+  for (const tool of TOOLS) {
+    if (await hasTool(tool)) await updateTool(tool, { prompt: false });
+    else await ensureTool(tool, { silent: true });
+  }
+}
+
+/** Update a single tool to its latest available version (best-effort). */
+export async function updateTool(tool, { prompt = false } = {}) {
+  if (!(await hasTool(tool))) return ensureTool(tool, { silent: true });
+
+  const pm = detectPackageManager();
+  const pkg = packageNameFor(tool, pm);
+  if (!pm || !pkg) return false;
+
+  if (prompt) {
+    const want = await p.confirm({ message: `Update ${pc.cyan(tool.name)} now?`, initialValue: true });
+    if (p.isCancel(want) || !want) { p.log.message(pc.dim(`${tool.name} update skipped.`)); return true; }
+  }
+
+  p.log.step(`Updating ${tool.name}…`);
+  try {
+    const args = pm === 'pacman'
+      ? ['-Syu', '--noconfirm', pkg]
+      : pm === 'apk'
+        ? ['apk', 'upgrade', pkg]
+        : [pm, 'install', '-y', '--only-upgrade', pkg];
+    await runPrivileged(args);
+    p.log.success(`${tool.name} updated.`);
+    return true;
+  } catch (e) {
+    p.log.warn(`${tool.name} update failed: ${e.message}`);
+    return false;
+  }
+}
+
+/** Report companion-tool presence (sync) for `doctor`. */
+export function companionToolStatus() {
+  return TOOLS.map((tool) => ({ name: tool.name, present: hasToolSync(tool) }));
 }

package/src/wizard/browse.js

@@ -2,8 +2,9 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import fs from 'node:fs';
 import path from 'node:path';
+import { execa } from 'execa';
 import { parseThemes, resolveConfPath } from '../lib/conf.js';
-import { ensureChafa } from '../lib/chafa.js';
+import { ensureManagedTools } from '../lib/tools.js';
 import { resolveEngine, USER_DIR } from '../core/engine.js';
 
 const USER_THEMES = path.join(USER_DIR, 'themes');
@@ -35,6 +36,11 @@ const statusColor = (status) => ({
   remote: pc.dim,
 }[status] || pc.dim);
 
+/** True when a theme has been downloaded into the local user cache. */
+function isCached(name) {
+  return fs.existsSync(path.join(USER_THEMES, name));
+}
+
 /**
  * Render a terminal "thumbnail" preview of a cached theme via chafa (or any
  * terminal image renderer the user has). Silently nops when unsatisfiable.
@@ -50,7 +56,6 @@ export async function showThemePreview({ name, width = 40, height = 12 }) {
     .sort()[0];
   if (!image) return false;
 
-  const { execa } = await import('execa');
   for (const tool of ['chafa', 'timg', 'viu', 'jp2a']) {
     const args = tool === 'chafa'
       ? ['--size', `${width}x${height}`, image]
@@ -63,103 +68,130 @@ export async function showThemePreview({ name, width = 40, height = 12 }) {
       }
     } catch { /* try next */ }
   }
-  p.log.message(pc.dim('Install `chafa` (: sudo apt install chafa) for terminal theme previews.'));
+  p.log.message(pc.dim('Install `chafa` (sudo apt install chafa) for terminal theme previews.'));
   return false;
 }
 
-/** Interactive GRUB-theme browser wizard (mirrors GitSwitch's look & feel). */
-export async function runThemeBrowser() {
-  // Step 1: ensure the thumbnail renderer is present before anything else.
-  await ensureChafa();
-
-  const themes = parseThemes(resolveConfPath());
-  const active = activeTheme();
-
-  const selected = await p.select({
-    message: pc.bold('Pick a GRUB theme'),
-    options: themes.map((t) => {
-      const status = themeStatus(t.name);
-      const color = statusColor(status);
-      return {
-        value: t,
-        label: `${t.name}  ${color(`[${status.toUpperCase()}]`)}${t.name === active ? '  ⭐' : ''}`,
-        hint: t.tags.slice(0, 3).join(', '),
-      };
-    }),
-  });
-  if (p.isCancel(selected)) { p.cancel('Bye! 👋'); process.exit(0); }
-
-  p.log.step(`${pc.bold(selected.name)} — ${selected.desc}`);
-  p.log.message(pc.dim(selected.url));
-
-  if (fs.existsSync(path.join(USER_THEMES, selected.name))) {
-    await showThemePreview({ name: selected.name });
+/**
+ * Make sure a theme is present in the local cache, downloading on demand.
+ * @returns {Promise<boolean>} true when the theme is cached (ready to preview/apply)
+ */
+async function ensureCached(engine, name) {
+  if (isCached(name)) return true;
+  p.log.warn(`${name} isn't downloaded yet. Fetching first…`);
+  const s = p.spinner();
+  s.start(`Downloading ${name}…`);
+  try {
+    await execa('bash', [engine, 'get', name], { stdio: 'inherit', reject: true });
+    s.stop(pc.green(`Downloaded ${name}.`));
+    return true;
+  } catch (e) {
+    s.stop(pc.red(`Download failed: ${e.message}`));
+    return false;
   }
+}
 
-  const action = await p.select({
-    message: `What do you want to do with ${pc.cyan(selected.name)}?`,
-    options: [
-      { value: 'preview', label: 'Show terminal thumbnail preview', hint: 'requires chafa + cached theme' },
-      { value: 'get', label: 'Download / update it', hint: 'git clone into local cache' },
-      { value: 'use', label: 'Apply to GRUB', hint: 'needs sudo; rebuilds GRUB' },
-      { value: 'open', label: 'Open source page in browser' },
-      { value: 'back', label: 'Cancel' },
-    ],
-  });
-  if (p.isCancel(action) || action === 'back') { p.outro('Bye! 👋'); process.exit(0); }
+/**
+ * Interactive GRUB-theme browser wizard (mirrors GitSwitch's look & feel).
+ * Stays in a menu loop: pick a theme → preview / download / apply / open →
+ * back to the theme list — it NEVER hard-exits until you choose Quit.
+ */
+export async function runThemeBrowser() {
+  // Step 1: ensure companion tools (chafa, grub-customizer) — detect, install
+  // or update, then continue BEFORE showing the theme picker.
+  await ensureManagedTools();
 
   const engine = await resolveEngine();
-  const { execa } = await import('execa');
-
-  if (action === 'preview') {
-    await showThemePreview({ name: selected.name, width: 80, height: 20 });
-    p.outro(pc.green('Preview above.'));
-  } else if (action === 'get') {
-    const s = p.spinner();
-    s.start(`Downloading ${selected.name}…`);
-    try {
-      await execa('bash', [engine, 'get', selected.name], { stdio: 'inherit', reject: true });
-      s.stop(pc.green(`Downloaded ${selected.name}.`));
-    } catch (e) {
-      s.stop(pc.red(`Download failed: ${e.message}`));
+  let quit = false;
+
+  while (!quit) {
+    const themes = parseThemes(resolveConfPath());
+    const active = activeTheme();
+
+    const picked = await p.select({
+      message: pc.bold('Pick a GRUB theme'),
+      options: themes.map((t) => {
+        const status = themeStatus(t.name);
+        const color = statusColor(status);
+        return {
+          value: t,
+          label: `${t.name}  ${color(`[${status.toUpperCase()}]`)}${t.name === active ? '  ⭐' : ''}`,
+          hint: (isCached(t.name) ? '🖼 ' : '') + t.tags.slice(0, 3).join(', '),
+        };
+      }),
+    });
+    if (p.isCancel(picked)) { quit = true; break; }
+
+    p.log.step(`${pc.bold(picked.name)} — ${picked.desc}`);
+    p.log.message(pc.dim(picked.url));
+
+    // Thumbnails render by default: show the preview whenever the theme is
+    // cached, otherwise point the user at Download to unlock it.
+    const cached = isCached(picked.name);
+    if (cached) {
+      await showThemePreview({ name: picked.name });
+    } else {
+      p.log.message(pc.dim('Not cached yet — choose “Download / update it” below to preview it.'));
+    }
+
+    // Per-theme action loop: runs until the user goes back to the list or quits.
+    let backToMenu = false;
+    while (!quit && !backToMenu) {
+      const action = await p.select({
+        message: `What do you want to do with ${pc.cyan(picked.name)}?`,
+        options: [
+          { value: 'preview', label: 'Preview terminal thumbnail', hint: cached ? 'renders below' : 'downloads first' },
+          { value: 'get', label: 'Download / update it', hint: 'git clone into local cache' },
+          { value: 'use', label: 'Apply to GRUB', hint: 'needs sudo; rebuilds GRUB' },
+          { value: 'open', label: 'Open source page in browser' },
+          { value: 'menu', label: '← Back to theme list' },
+          { value: 'quit', label: 'Quit browser' },
+        ],
+      });
+
+      if (p.isCancel(action) || action === 'quit') { quit = true; break; }
+      if (action === 'menu') { backToMenu = true; break; }
+
+      if (action === 'preview') {
+        if (await ensureCached(engine, picked.name)) {
+          await showThemePreview({ name: picked.name, width: 80, height: 22 });
+        }
+      } else if (action === 'get') {
+        await ensureCached(engine, picked.name);
+      } else if (action === 'use') {
+        await runUse(engine, picked.name);
+      } else if (action === 'open') {
+        await execa('bash', [engine, 'open', picked.name], { stdio: 'inherit', reject: false });
+      }
     }
-  } else if (action === 'use') {
-    await runUse(engine, selected.name);
-  } else if (action === 'open') {
-    await execa('bash', [engine, 'open', selected.name], { stdio: 'inherit', reject: false });
   }
+
+  p.outro(pc.cyan('Bye! 👋'));
 }
 
-/** Apply a theme to GRUB, re-invoking with sudo, spinner released for the prompt. */
+/**
+ * Apply a theme to GRUB, re-invoking with sudo, spinner released for the prompt.
+ * Returns true when the apply was attempted/succeeded (false if aborted).
+ */
 export async function runUse(engine, name) {
-  const cached = path.join(USER_THEMES, name);
-  if (!fs.existsSync(cached)) {
-    p.log.warn(`${name} isn't downloaded yet. Fetching first…`);
-    const s = p.spinner();
-    s.start(`Downloading ${name}…`);
-    try {
-      await execa('bash', [engine, 'get', name], { stdio: 'inherit', reject: true });
-      s.stop();
-    } catch (e) {
-      s.stop(pc.red(`Download failed: ${e.message}`));
-      return;
-    }
-  }
+  if (!(await ensureCached(engine, name))) { p.cancel('Aborted — theme not downloaded.'); return false; }
 
   const confirmApply = await p.confirm({ message: `Apply ${pc.cyan(name)} to GRUB and rebuild? (sudo)`, initialValue: true });
-  if (p.isCancel(confirmApply) || !confirmApply) { p.outro('Skipped.'); return; }
+  if (p.isCancel(confirmApply) || !confirmApply) {
+    p.log.message(pc.dim('Skipped — theme not applied.'));
+    return false;
+  }
 
-  const { execa } = await import('execa');
   if (process.getuid() !== 0) {
     // Release spinner, then prompt sudo on a clean terminal so Ctrl+C works.
     console.log();
     const res = await execa('sudo', ['bash', engine, 'use', name], { stdio: 'inherit', reject: false });
-    return res.exitCode === 0
-      ? p.outro(pc.green(`${name} is now your GRUB theme! 🎉`))
-      : p.cancel('GRUB apply failed.');
+    if (res.exitCode === 0) { p.log.success(`${name} is now your GRUB theme! 🎉`); return true; }
+    p.cancel('GRUB apply failed.');
+    return false;
   }
   const res = await execa('bash', [engine, 'use', name], { stdio: 'inherit', reject: false });
-  res.exitCode === 0
-    ? p.outro(pc.green(`${name} is now your GRUB theme! 🎉`))
-    : p.cancel('GRUB apply failed.');
-}
+  if (res.exitCode === 0) { p.log.success(`${name} is now your GRUB theme! 🎉`); return true; }
+  p.cancel('GRUB apply failed.');
+  return false;
+}

package/src/lib/chafa.js

@@ -1,143 +0,0 @@
-import { execa, execaSync } from 'execa';
-import pc from 'picocolors';
-import * as p from '@clack/prompts';
-
-/**
- * chafa — the terminal image renderer behind theamify's thumbnail previews.
- * This module manages chafa as a first-class wizard dependency:
- *   - install   when the wizard runs and chafa is missing
- *   - update    when the wizard updates itself
- *   - uninstall when the wizard is uninstalled (opt-in)
- */
-
-export const CHAFA_BIN = 'chafa';
-
-/** @returns {Promise<boolean>} true if `chafa` is on PATH. */
-export async function hasChafa() {
-  try {
-    const res = await execa('bash', ['-c', `command -v ${CHAFA_BIN}`], { reject: false });
-    return Boolean(res.stdout.trim());
-  } catch {
-    return false;
-  }
-}
-
-/** Detect which package manager is available. @returns {string|null} */
-export function detectPackageManager() {
-  const order = ['apt-get', 'dnf', 'yum', 'pacman', 'zypper', 'apk'];
-  const pm = order.find((name) => {
-    try {
-      return Boolean(execaSync('bash', ['-c', `command -v ${name}`], { reject: false }).stdout.trim());
-    } catch {
-      return false;
-    }
-  });
-  return pm || null;
-}
-
-/**
- * Run a privileged package-manager command, releasing the terminal first so the
- * sudo password prompt is visible and Ctrl+C actually works. Mirrors the
- * interactive-sudo pattern used by gitswitch and warp-wizard.
- * @param {string[]} cmd sudo + args
- */
-async function runPrivileged(cmd) {
-  const res = await execa('sudo', cmd, { stdio: 'inherit', reject: false });
-  if (res.exitCode !== 0) throw new Error(`Command failed: sudo ${cmd.join(' ')} (exit ${res.exitCode})`);
-  return res;
-}
-
-/**
- * Install chafa, prompting the user first. Safe no-op when a package manager is
- * unavailable or chafa is already installed.
- * @param {{silent?: boolean}} [opts]
- * @returns {Promise<boolean>} true when chafa is available afterwards
- */
-export async function ensureChafa({ silent = false } = {}) {
-  if (await hasChafa()) return true;
-
-  const pm = detectPackageManager();
-  if (!pm) {
-    if (!silent) p.log.warn('No supported package manager found — install chafa manually to enable previews.');
-    return false;
-  }
-
-  const want = silent ? true : await p.confirm({
-    message: `Install ${pc.cyan('chafa')} to enable terminal theme previews?`,
-    initialValue: true,
-  });
-  if (p.isCancel(want) || !want) {
-    if (!silent) p.log.message(pc.dim('Skipped — theme thumbnails will be disabled. Install later with your package manager.'));
-    return false;
-  }
-
-  if (!silent) p.log.step(`Installing chafa via ${pm}…`);
-  const s = p.spinner();
-  s.start('Installing chafa…');
-  try {
-    // Release the spinner so the sudo prompt is visible & interruptible.
-    s.stop('');
-    const pkgArgs = pm === 'pacman' ? ['-S', '--noconfirm', 'chafa'] : [pm, 'install', '-y', 'chafa'];
-    await runPrivileged(pkgArgs);
-    if (!(await hasChafa())) throw new Error('chafa install appeared to complete, but chafa is not on PATH.');
-    if (!silent) p.log.success('chafa installed — terminal thumbnails enabled!');
-    return true;
-  } catch (e) {
-    if (!silent) p.log.warn(`chafa install failed: ${e.message}\n  Try manually: sudo apt install chafa`);
-    return false;
-  }
-}
-
-/** Update chafa to its latest available version (best-effort). */
-export async function updateChafa() {
-  if (!(await hasChafa())) return ensureChafa({ silent: true });
-
-  const pm = detectPackageManager();
-  if (!pm) return false;
-  p.log.step('Updating chafa…');
-  try {
-    const args = pm === 'pacman'
-      ? ['-Syu', '--noconfirm', 'chafa']
-      : pm === 'apk'
-        ? ['apk', 'upgrade', 'chafa']
-        : [pm, 'install', '-y', '--only-upgrade', 'chafa'];
-    await runPrivileged(args);
-    p.log.success('chafa updated.');
-    return true;
-  } catch (e) {
-    p.log.warn(`chafa update failed: ${e.message}`);
-    return false;
-  }
-}
-
-/**
- * Remove chafa after confirming. Only called from the uninstall wizard.
- * @returns {Promise<boolean>} true when chafa was removed
- */
-export async function uninstallChafa() {
-  if (!(await hasChafa())) { p.log.message(pc.dim('chafa not installed — nothing to remove.')); return false; }
-
-  const pm = detectPackageManager();
-  if (!pm) { p.log.warn('No package manager found — remove chafa yourself.'); return false; }
-
-  const want = await p.confirm({
-    message: 'Also remove chafa (thumbnail renderer)? You can re-enable previews later by reinstalling it.',
-    initialValue: false,
-  });
-  if (p.isCancel(want) || !want) { p.log.message(pc.dim('Kept chafa.')); return false; }
-
-  p.log.step(`Removing chafa via ${pm}…`);
-  try {
-    const args = pm === 'pacman'
-      ? ['pacman', '-Rns', '--noconfirm', 'chafa']
-      : pm === 'apk'
-        ? ['apk', 'del', 'chafa']
-        : [pm, 'remove', '-y', 'chafa'];
-    await runPrivileged(args);
-    p.log.success('chafa removed.');
-    return true;
-  } catch (e) {
-    p.log.warn(`chafa removal failed: ${e.message}`);
-    return false;
-  }
-}