theamify-cli 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Don Artkins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+# 🎨 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`**.
+
+---
+
+## 🚀 Install (global — run from anywhere)
+
+**One command, installed globally so `theamify` works from any directory on your machine:**
+
+```bash
+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**:
+
+```bash
+theamify                    # ✨ interactive theme browser wizard
+theamify list               # list all themes with status
+theamify info <name>        # details + terminal preview (needs chafa)
+theamify get <name>         # download & cache a theme
+sudo theamify use <name>    # apply to GRUB + rebuild
+theamify status             # GRUB & dependency status
+theamify doctor             # diagnose install, GRUB & dependencies
+theamify uninstall          # remove theamify (asks before deleting anything)
+```
+
+> 💡 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
+> ```
+
+---
+
+## ✨ What's New in v1.0.0 (npm wizard 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 |
+
+---
+
+## 📋 Requirements
+
+| Tool | Purpose |
+|---|---|
+| `bash` | Runs the theamify engine |
+| `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`) |
+
+---
+
+## Rosetta Stone — classic tool vs npm CLI
+
+The npm CLI is a thin Node wrapper around the original Bash engine, so every
+non-interactive command still behaves identically:
+
+| npm CLI | Original tool |
+|---|---|
+| `theamify list` | `theamify list` |
+| `theamify get <n>` | `theamify get <n>` |
+| `sudo theamify use <n>` | `sudo theamify use <n>` |
+| `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.
+
+---
+
+## Theme Previews in the Terminal
+
+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`.
+
+```bash
+theamify            # Step 1: ensures chafa (prompts to install if missing)
+```
+
+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
+```
+
+---
+
+## 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) |
+
+---
+
+## 📁 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/bin/theamify.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "theamify-cli",
+  "version": "1.0.1",
+  "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",
+  "bin": {
+    "theamify": "bin/theamify.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "vendor/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "npm run test:syntax && node --test",
+    "test:syntax": "bash -n vendor/theamify && bash -n vendor/lib/utils.sh && bash -n vendor/lib/grub.sh && bash -n vendor/lib/themes.sh && bash -n vendor/lib/colors.sh",
+    "publish:dry-run": "npm publish --dry-run --access public",
+    "release:patch": "npm test && npm version patch -m \"chore(release): %s\" && git push origin main --follow-tags",
+    "release:minor": "npm test && npm version minor -m \"chore(release): %s\" && git push origin main --follow-tags",
+    "release:major": "npm test && npm version major -m \"chore(release): %s\" && git push origin main --follow-tags"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DonArtkins/theamify.git"
+  },
+  "homepage": "https://github.com/DonArtkins/theamify#readme",
+  "bugs": {
+    "url": "https://github.com/DonArtkins/theamify/issues"
+  },
+  "keywords": [
+    "grub",
+    "theme",
+    "grub-theme",
+    "linux",
+    "boot",
+    "wizard",
+    "cli",
+    "theamify"
+  ],
+  "author": "Don Artkins (https://github.com/DonArtkins)",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "citty": "^0.2.2",
+    "execa": "^8.0.1",
+    "picocolors": "^1.1.1"
+  }
+}

package/src/cli.js

@@ -0,0 +1,109 @@
+import { defineCommand, runMain } from 'citty';
+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 { runEngine } from './core/engine.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+/** Commands forwarded straight to the bash engine. */
+const ENGINE_COMMANDS = ['list', 'ls', 'info', 'show', 'get', 'fetch', 'download', 'remove', 'rm', 'uncache', 'add', 'del', 'delete', 'update', 'open', 'browse', 'clean', 'purge-cache', 'help', '-h', '-V', '--version'];
+
+/**
+ * Forward argv to the bash engine and mirror its exit status onto this process.
+ * @param {string[]} args
+ */
+async function forwardEngine(args) {
+  const res = await runEngine(args);
+  if (res && Number.isInteger(res.exitCode) && res.exitCode !== 0) {
+    process.exitCode = res.exitCode;
+  }
+  return res;
+}
+
+function printUsage() {
+  console.log(`
+${pc.bold('theamify')} ${pc.dim(`v${pkg.version}`)} — GRUB theme manager
+
+${pc.bold('Usage:')}
+  theamify                    ✨ Interactive theme browser wizard (pick → preview → apply)
+  theamify list               List all themes with status
+  theamify info <name>        Show details + terminal preview (needs chafa)
+  theamify get <name>         Download & cache a theme
+  theamify get --all          Download every theme
+  theamify use <name>         Apply theme to GRUB ${pc.dim('[sudo]')}
+  theamify update [<name>]    Re-download cached themes
+  theamify remove <name>      Clear local cache (keeps registry entry)
+  theamify add <github-url>   Add a theme to the registry
+  theamify del <name>         Remove a theme from the registry
+  theamify open <name>        Open the theme source page in a browser
+  theamify status             Show GRUB & dependency status
+  theamify doctor             Diagnose install, GRUB & dependencies
+  theamify uninstall          Remove theamify (asks before deleting anything)
+  theamify clean              Clear the repo clone cache
+`);
+}
+
+/**
+ * Terminal safety net: when an interactive child (sudo password prompt) is
+ * running, the terminal is in canonical mode and Ctrl+C/Z arrive as real
+ * signals. Restore the cursor and exit cleanly instead of hanging.
+ */
+function terminateAndRestore(code) {
+  try {
+    if (process.stdout.isTTY) process.stdout.write('\x1b[?25h\n\r');
+  } catch { /* best effort */ }
+  process.exit(code);
+}
+if (process.platform !== 'win32') process.on('SIGTSTP', () => terminateAndRestore(130)); // Ctrl+Z
+process.on('SIGINT', () => terminateAndRestore(130));  // Ctrl+C
+process.on('SIGTERM', () => terminateAndRestore(143)); // kill/terminate
+
+const main = defineCommand({
+  meta: {
+    name: 'theamify',
+    version: pkg.version,
+    description: 'GRUB theme manager & interactive browser wizard',
+  },
+  async run({ args }) {
+    const [cmd, ...rest] = args._;
+
+    // No arguments → the interactive theme browser wizard.
+    if (!cmd) return runThemeBrowser();
+
+    switch (cmd) {
+      case 'wizard':
+      case 'browse':
+        return runThemeBrowser();
+      case 'status':
+        return runStatus();
+      case 'doctor':
+        return runDoctor();
+      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();
+        return forwardEngine(['update', ...rest]);
+      case 'use':
+      case 'apply':
+      case 'set':
+        return forwardEngine(['use', ...rest]);
+      case 'info':
+      case 'show':
+        return forwardEngine(['info', ...rest]);
+      default:
+        if (ENGINE_COMMANDS.includes(cmd)) return forwardEngine(args._);
+        console.error(pc.red(`Unknown command: ${cmd}`));
+        printUsage();
+        process.exitCode = 1;
+        return undefined;
+    }
+  },
+});
+
+runMain(main);

package/src/commands/manage.js

@@ -0,0 +1,122 @@
+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 {
+  findInstalledRuntime,
+  USER_DIR,
+  USER_BIN_LINK,
+  resolveEngine,
+} from '../core/engine.js';
+import { parseThemes } from '../lib/conf.js';
+import { uninstallChafa } from '../lib/chafa.js';
+
+/** `theamify doctor` — installation, GRUB and dependency health. */
+export async function runDoctor() {
+  console.log(pc.bold('\n🩺 theamify Doctor\n'));
+
+  const found = findInstalledRuntime();
+  const engine = await resolveEngine();
+  console.log(`  Engine   : ${pc.cyan(engine)}`);
+  console.log(`  Runtime  : ${found ? pc.cyan(found.dir) : pc.dim('(provisioned on demand)')}`);
+
+  // Registry / theme count
+  try {
+    const themes = parseThemes();
+    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})`)}`);
+  }
+
+  // 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 ''; }
+}
+
+function grubDetectDir() {
+  for (const d of ['/boot/grub/themes', '/boot/grub2/themes', '/usr/share/grub/themes']) {
+    if (fs.existsSync(d)) return d;
+  }
+  return '/boot/grub/themes';
+}
+
+/** Name of the currently-active GRUB theme, from /etc/default/grub. */
+function activeThemeLabel() {
+  try {
+    const cfg = fs.readFileSync('/etc/default/grub', 'utf8');
+    const m = cfg.match(/^GRUB_THEME="?([^"\n]+)"?/m);
+    if (!m) return '';
+    const dir = path.dirname(m[1]);
+    return (dir === '.' ? '' : path.basename(dir)) || m[1];
+  } catch {
+    return '';
+  }
+}
+
+/** `theamify status` — compact runtime status (wraps engine). */
+export async function runStatus() {
+  const engine = await resolveEngine();
+  const res = await execa('bash', [engine, 'status'], { stdio: 'inherit', reject: false });
+  if (res.exitCode !== 0) process.exit(res.exitCode);
+}
+
+/** `theamify uninstall` — interactive, every destructive step confirmed. */
+export async function runUninstallWizard() {
+  p.intro(pc.bgRed(pc.black(' theamify Uninstaller ')));
+  const found = findInstalledRuntime();
+  if (!found) p.log.info('No installed theamify runtime found (nothing to remove).');
+
+  let removed = false;
+  if (found) {
+    const confirm = await p.confirm({
+      message: `Remove theamify files at ${found.dir}/?`,
+      initialValue: true,
+    });
+    if (!p.isCancel(confirm) && confirm) {
+      try {
+        const dir = found.dir;
+        const owner = fs.statSync(dir).uid;
+        if (owner === 0 && process.getuid() !== 0) {
+          await execa('sudo', ['rm', '-rf', dir], { stdio: 'inherit' });
+        } else {
+          fs.rmSync(dir, { recursive: true, force: true });
+        }
+        removed = true;
+        // remove the PATH symlink arm (never touches ~/.bashrc blocks without asking? leave PATH block — it's harmless)
+        if (USER_BIN_LINK.startsWith(USER_DIR)) {
+          fs.rmSync(USER_BIN_LINK, { force: true });
+        }
+      } catch {
+        p.log.warn(`Could not remove ${found.dir}.`);
+      }
+    }
+  }
+
+  const keepGrub = await p.confirm({
+    message: 'Keep your currently-applied GRUB theme? (recommended)',
+    initialValue: true,
+  });
+  if (p.isCancel(keepGrub)) { p.cancel('Aborted.'); process.exit(0); }
+
+  // Optionally remove the thumbnail renderer the wizard installed.
+  await uninstallChafa();
+
+  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.'}`,
+  ));
+}