shell-logo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Chiti
+
+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,70 @@
+# shell-logo
+
+Now that we are all coding with 1232 terminals open, is kind of hard to quickly find the one you want at a glance.
+Adding a small configurable logo to quickly spot each project.
+
+![screen-capture](assets/mosaic.jpeg)
+
+## Install
+
+```bash
+npm i -g shell-logo
+# or
+pnpm add -g shell-logo
+```
+
+## Usage
+
+```bash
+shell-logo
+```
+
+Launches an interactive menu where you can:
+
+1. **Generate** - create a new `.shell-logo.json` config by picking text, colors, and a font
+2. **Run** - display the logo from an existing `.shell-logo.json` in the current directory
+
+Once the logo is displayed, use arrow keys to cycle through themes and `q` to quit.
+
+## Config
+
+The generated `.shell-logo.json` looks like this:
+
+```json
+{
+  "text": "My Project",
+  "font": "Standard",
+  "colors": ["#ff6b6b", "#feca57"],
+  "padding": 1
+}
+```
+
+| Field     | Type       | Default                             | Description                       |
+| --------- | ---------- | ----------------------------------- | --------------------------------- |
+| `text`    | `string`   | _(required)_                        | The text to render as ASCII art   |
+| `font`    | `string`   | `"Standard"`                        | Figlet font name                  |
+| `colors`  | `string[]` | `["#ff6b6b", "#feca57", "#48dbfb"]` | Hex colors for the gradient (>=2) |
+| `padding` | `number`   | `1`                                 | Vertical padding above the logo   |
+
+See `examples/` for more config samples.
+
+## Publishing to npm
+
+```bash
+# 1. Make sure you're logged in
+npm login
+
+# 2. Do a dry run to verify what gets packed
+npm pack --dry-run
+
+# 3. Publish
+npm publish
+
+# For subsequent releases, bump the version first
+npm version patch  # or minor / major
+npm publish
+```
+
+## License
+
+MIT

package/examples/.shell-logo.json

@@ -0,0 +1,6 @@
+{
+  "text": "HELLO",
+  "colors": ["#ff6b6b", "#feca57", "#48dbfb"],
+  "font": "Standard",
+  "padding": 1
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "shell-logo",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Render colorful ASCII art logos in the terminal from a config file",
+  "license": "MIT",
+  "author": "Rafael Chiti",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rafaelchiti/shell-logo.git"
+  },
+  "homepage": "https://github.com/rafaelchiti/shell-logo",
+  "bugs": {
+    "url": "https://github.com/rafaelchiti/shell-logo/issues"
+  },
+  "bin": {
+    "shell-logo": "./src/index.js"
+  },
+  "keywords": [
+    "cli",
+    "terminal",
+    "ascii-art",
+    "logo",
+    "figlet",
+    "gradient"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "examples/"
+  ],
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "figlet": "^1.8.0",
+    "@clack/prompts": "^0.11.0",
+    "gradient-string": "^3.0.0"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  }
+}

package/src/config.js

@@ -0,0 +1,91 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+
+export const DEFAULTS = {
+  colors: ['#ff6b6b', '#feca57', '#48dbfb'],
+  font: 'Standard',
+};
+
+export function tryLoadConfig() {
+  const configPath = join(process.cwd(), '.shell-logo.json');
+
+  let raw;
+  try {
+    raw = readFileSync(configPath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (!config.text || typeof config.text !== 'string' || config.text.trim() === '') {
+    return null;
+  }
+
+  if (config.colors !== undefined) {
+    if (!Array.isArray(config.colors) || config.colors.length < 2) {
+      return null;
+    }
+  }
+
+  return {
+    text: config.text.trim(),
+    colors: config.colors ?? DEFAULTS.colors,
+    font: config.font ?? DEFAULTS.font,
+  };
+}
+
+export function loadConfig() {
+  const configPath = join(process.cwd(), '.shell-logo.json');
+
+  let raw;
+  try {
+    raw = readFileSync(configPath, 'utf-8');
+  } catch {
+    console.error(
+      chalk.red('Error: ') +
+        'No .shell-logo.json found in the current directory.\n\n' +
+        'Create one with at least:\n\n' +
+        '  { "text": "HELLO" }\n\n' +
+        'Or copy an example:\n\n' +
+        '  cp node_modules/shell-logo/examples/.shell-logo.json .'
+    );
+    process.exit(1);
+  }
+
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch {
+    console.error(chalk.red('Error: ') + '.shell-logo.json contains invalid JSON.');
+    process.exit(1);
+  }
+
+  if (!config.text || typeof config.text !== 'string' || config.text.trim() === '') {
+    console.error(
+      chalk.red('Error: ') + '"text" is required and must be a non-empty string in .shell-logo.json.'
+    );
+    process.exit(1);
+  }
+
+  if (config.colors !== undefined) {
+    if (!Array.isArray(config.colors) || config.colors.length < 2) {
+      console.error(
+        chalk.red('Error: ') + '"colors" must be an array of at least 2 color strings.'
+      );
+      process.exit(1);
+    }
+  }
+
+  return {
+    text: config.text.trim(),
+    colors: config.colors ?? DEFAULTS.colors,
+    font: config.font ?? DEFAULTS.font,
+  };
+}

package/src/generate.js

@@ -0,0 +1,8 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function writeConfig(config) {
+  const configPath = join(process.cwd(), '.shell-logo.json');
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  return configPath;
+}

package/src/index.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { runInteractiveUI } from './ui.js';
+import { writeConfig } from './generate.js';
+import { render } from './renderer.js';
+import { getTerminalSize, clearScreen, hideCursor, showCursor, centerContent } from './terminal.js';
+import { THEMES, FONTS } from './themes.js';
+import chalk from 'chalk';
+import * as p from '@clack/prompts';
+
+const { action, config } = await runInteractiveUI();
+
+if (action === 'generate') {
+  const s = p.spinner();
+  s.start('Writing .shell-logo.json...');
+  writeConfig(config);
+  s.stop('Config saved!');
+
+  const isGitRepo = existsSync(join(process.cwd(), '.git'));
+  const gitignorePath = join(process.cwd(), '.gitignore');
+  let shouldPrompt = isGitRepo;
+
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, 'utf-8');
+    const lines = content.split('\n').map(l => l.trim());
+    if (lines.includes('.shell-logo.json')) {
+      shouldPrompt = false;
+    }
+  }
+
+  if (shouldPrompt) {
+    const addToGitignore = await p.select({
+      message: 'Add .shell-logo.json to .gitignore?',
+      options: [
+        { value: true, label: 'Yes (recommended)' },
+        { value: false, label: 'No' },
+      ],
+    });
+
+    if (p.isCancel(addToGitignore)) {
+      p.cancel('Cancelled.');
+      process.exit(0);
+    }
+
+    if (addToGitignore) {
+      if (existsSync(gitignorePath)) {
+        const existing = readFileSync(gitignorePath, 'utf-8');
+        const separator = existing.endsWith('\n') ? '' : '\n';
+        writeFileSync(gitignorePath, existing + separator + '.shell-logo.json\n');
+      } else {
+        writeFileSync(gitignorePath, '.shell-logo.json\n');
+      }
+      p.log.success('.gitignore updated.');
+    }
+  }
+}
+
+startRenderLoop(config);
+
+function startRenderLoop(config) {
+  let resizeTimer;
+
+  // Find the current theme index by matching colors
+  let themeIndex = THEMES.findIndex(
+    (t) => JSON.stringify(t.colors) === JSON.stringify(config.colors)
+  );
+  if (themeIndex === -1) themeIndex = 0;
+
+  let fontIndex = FONTS.indexOf(config.font);
+  if (fontIndex === -1) fontIndex = 0;
+
+  let showStatus = false;
+  let statusTimer;
+
+  function renderLoop() {
+    const { columns, rows } = getTerminalSize();
+    const art = render(config, columns, rows);
+    clearScreen();
+    process.stdout.write(centerContent(art, columns, rows));
+    if (showStatus) {
+      const status = `  ${THEMES[themeIndex].name}  ·  ${FONTS[fontIndex]}  ·  ↑↓ theme  ←→ font  q quit`;
+      process.stdout.write(`\x1B[${rows};1H` + chalk.dim(status));
+    }
+  }
+
+  function flashStatus() {
+    showStatus = true;
+    clearTimeout(statusTimer);
+    statusTimer = setTimeout(() => {
+      showStatus = false;
+      renderLoop();
+    }, 2000);
+  }
+
+  function debouncedRender() {
+    clearTimeout(resizeTimer);
+    resizeTimer = setTimeout(renderLoop, 50);
+  }
+
+  function cleanup() {
+    showCursor();
+    clearScreen();
+    process.exit(0);
+  }
+
+  // Raw mode AFTER prompts are done
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  hideCursor();
+  renderLoop();
+
+  // Show controls help on startup for 4 seconds
+  showStatus = true;
+  statusTimer = setTimeout(() => {
+    showStatus = false;
+    renderLoop();
+  }, 4000);
+
+  process.stdout.on('resize', debouncedRender);
+
+  process.stdin.on('data', (key) => {
+    if (key[0] === 3 || key[0] === 113) cleanup(); // Ctrl+C or q
+
+    // Arrow up/down are 3-byte escape sequences
+    if (key[0] === 27 && key[1] === 91) {
+      if (key[2] === 65) { // Arrow Up — prev theme
+        themeIndex = (themeIndex - 1 + THEMES.length) % THEMES.length;
+        config.colors = THEMES[themeIndex].colors;
+      } else if (key[2] === 66) { // Arrow Down — next theme
+        themeIndex = (themeIndex + 1) % THEMES.length;
+        config.colors = THEMES[themeIndex].colors;
+      } else if (key[2] === 67) { // Arrow Right — next font
+        fontIndex = (fontIndex + 1) % FONTS.length;
+        config.font = FONTS[fontIndex];
+      } else if (key[2] === 68) { // Arrow Left — prev font
+        fontIndex = (fontIndex - 1 + FONTS.length) % FONTS.length;
+        config.font = FONTS[fontIndex];
+      } else {
+        return;
+      }
+      writeConfig(config);
+      flashStatus();
+      renderLoop();
+    }
+
+  });
+  process.on('SIGTERM', cleanup);
+}

package/src/renderer.js

@@ -0,0 +1,24 @@
+import figlet from 'figlet';
+import gradient from 'gradient-string';
+import { scaleArt } from './scaling.js';
+
+function figletSync(text, font) {
+  try {
+    return figlet.textSync(text, { font });
+  } catch {
+    return null;
+  }
+}
+
+export function render(config, columns, rows) {
+  const art = figletSync(config.text, config.font);
+  if (!art) {
+    const grad = gradient(config.colors);
+    return grad(config.text.slice(0, columns));
+  }
+
+  const trimmed = art.trimEnd();
+  const scaled = scaleArt(trimmed, columns, rows - 2);
+  const grad = gradient(config.colors);
+  return grad.multiline(scaled);
+}

package/src/scaling.js

@@ -0,0 +1,39 @@
+export function measureArt(art) {
+  const lines = art.split('\n');
+  const width = lines.reduce((max, line) => Math.max(max, line.length), 0);
+  return { width, height: lines.length };
+}
+
+export function scaleArt(art, targetWidth, targetHeight) {
+  const lines = art.split('\n');
+  const { width: artWidth, height: artHeight } = measureArt(art);
+
+  if (artWidth <= targetWidth && artHeight <= targetHeight) return art;
+
+  const scaleFactor = Math.min(
+    targetWidth / artWidth,
+    targetHeight / artHeight,
+    1.0
+  );
+
+  const newWidth = Math.floor(artWidth * scaleFactor);
+  const newHeight = Math.floor(artHeight * scaleFactor);
+
+  const result = [];
+  for (let j = 0; j < newHeight; j++) {
+    const srcRow = Math.floor(j * artHeight / newHeight);
+    const line = lines[srcRow] || '';
+    if (line.length === 0) {
+      result.push('');
+      continue;
+    }
+    const row = [];
+    for (let i = 0; i < newWidth; i++) {
+      const srcCol = Math.floor(i * artWidth / newWidth);
+      row.push(srcCol < line.length ? line[srcCol] : ' ');
+    }
+    result.push(row.join(''));
+  }
+
+  return result.join('\n');
+}

package/src/terminal.js

@@ -0,0 +1,42 @@
+// Strip ANSI escape codes when calculating visual width
+const ANSI_RE = /\x1B\[[0-9;]*m/g;
+
+export function getTerminalSize() {
+  return {
+    columns: process.stdout.columns || 80,
+    rows: process.stdout.rows || 24,
+  };
+}
+
+export function clearScreen() {
+  process.stdout.write('\x1B[2J\x1B[H');
+}
+
+export function hideCursor() {
+  process.stdout.write('\x1B[?25l');
+}
+
+export function showCursor() {
+  process.stdout.write('\x1B[?25h');
+}
+
+export function centerContent(text, columns, rows) {
+  const lines = text.split('\n');
+
+  // Calculate the max visual width (strip ANSI codes)
+  const maxWidth = lines.reduce((max, line) => {
+    const visual = line.replace(ANSI_RE, '').length;
+    return visual > max ? visual : max;
+  }, 0);
+
+  // Horizontal padding for each line
+  const leftPad = Math.max(0, Math.floor((columns - maxWidth) / 2));
+  const padStr = ' '.repeat(leftPad);
+
+  const paddedLines = lines.map((line) => padStr + line);
+
+  const contentHeight = paddedLines.length;
+  const topPad = Math.max(0, Math.floor((rows - contentHeight) / 2));
+
+  return '\n'.repeat(topPad) + paddedLines.join('\n');
+}

package/src/themes.js

@@ -0,0 +1,12 @@
+export const FONTS = ['Standard', 'Big', 'ANSI Shadow', 'Slant', 'Small'];
+
+export const THEMES = [
+  { name: 'Sunset',     colors: ['#ff6b6b', '#ff9f43', '#feca57'] },
+  { name: 'Ocean',      colors: ['#0abde3', '#48dbfb', '#54a0ff'] },
+  { name: 'Forest',     colors: ['#1dd1a1', '#2ed573', '#26de81'] },
+  { name: 'Neon',       colors: ['#c56cf0', '#fd79a8', '#ff6b6b'] },
+  { name: 'Twilight',   colors: ['#5f27cd', '#c56cf0', '#48dbfb'] },
+  { name: 'Fire',       colors: ['#ff4757', '#ff6348', '#ffdd59'] },
+  { name: 'Pastel',     colors: ['#fd79a8', '#feca57', '#48dbfb'] },
+  { name: 'Monochrome', colors: ['#ffffff', '#54a0ff', '#5f27cd'] },
+];

package/src/ui.js

@@ -0,0 +1,116 @@
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import { tryLoadConfig } from './config.js';
+
+const COLOR_PALETTE = [
+  { value: '#ff6b6b', label: `${chalk.bgHex('#ff6b6b')('   ')} Coral` },
+  { value: '#ff4757', label: `${chalk.bgHex('#ff4757')('   ')} Vibrant Red` },
+  { value: '#ff6348', label: `${chalk.bgHex('#ff6348')('   ')} Tomato` },
+  { value: '#feca57', label: `${chalk.bgHex('#feca57')('   ')} Golden` },
+  { value: '#ff9f43', label: `${chalk.bgHex('#ff9f43')('   ')} Orange` },
+  { value: '#ffdd59', label: `${chalk.bgHex('#ffdd59')('   ')} Lemon` },
+  { value: '#1dd1a1', label: `${chalk.bgHex('#1dd1a1')('   ')} Mint` },
+  { value: '#2ed573', label: `${chalk.bgHex('#2ed573')('   ')} Neon Green` },
+  { value: '#26de81', label: `${chalk.bgHex('#26de81')('   ')} Emerald` },
+  { value: '#48dbfb', label: `${chalk.bgHex('#48dbfb')('   ')} Sky` },
+  { value: '#0abde3', label: `${chalk.bgHex('#0abde3')('   ')} Cerulean` },
+  { value: '#54a0ff', label: `${chalk.bgHex('#54a0ff')('   ')} Cornflower` },
+  { value: '#5f27cd', label: `${chalk.bgHex('#5f27cd')('   ')} Deep Purple` },
+  { value: '#c56cf0', label: `${chalk.bgHex('#c56cf0')('   ')} Lavender` },
+  { value: '#fd79a8', label: `${chalk.bgHex('#fd79a8')('   ')} Pink` },
+  { value: '#ffffff', label: `${chalk.bgHex('#ffffff')('   ')} White` },
+];
+
+const FONT_OPTIONS = [
+  { value: 'Standard', label: 'Standard' },
+  { value: 'Big', label: 'Big' },
+  { value: 'ANSI Shadow', label: 'ANSI Shadow' },
+  { value: 'Slant', label: 'Slant' },
+  { value: 'Small', label: 'Small' },
+];
+
+function handleCancel(value) {
+  if (p.isCancel(value)) {
+    p.cancel('Cancelled.');
+    process.exit(0);
+  }
+  return value;
+}
+
+async function promptGenerate() {
+  const text = handleCancel(
+    await p.text({
+      message: 'What text should the logo display?',
+      placeholder: 'HELLO',
+      validate: (val) => {
+        if (!val || val.trim() === '') return 'Text is required.';
+      },
+    })
+  );
+
+  // Pick 3 random unique colors as defaults
+  const shuffled = [...COLOR_PALETTE].sort(() => Math.random() - 0.5);
+  const initialColors = shuffled.slice(0, 3).map(c => c.value);
+
+  let colors;
+  while (true) {
+    colors = handleCancel(
+      await p.multiselect({
+        message: 'Pick 2 or more colors for the gradient:',
+        options: COLOR_PALETTE,
+        initialValues: initialColors,
+        required: true,
+      })
+    );
+
+    if (colors.length >= 2) break;
+    p.log.warning('Please select at least 2 colors.');
+  }
+
+  const font = handleCancel(
+    await p.select({
+      message: 'Pick a font:',
+      options: FONT_OPTIONS,
+    })
+  );
+
+  return {
+    action: 'generate',
+    config: { text: text.trim(), colors, font },
+  };
+}
+
+export async function runInteractiveUI() {
+  p.intro(chalk.bold('terminal-logo'));
+
+  const hasConfig = !!tryLoadConfig();
+
+  const action = handleCancel(
+    await p.select({
+      message: 'What would you like to do?',
+      initialValue: hasConfig ? 'run' : 'generate',
+      options: [
+        { value: 'generate', label: 'Generate', hint: 'create .shell-logo.json' },
+        { value: 'run', label: 'Run', hint: 'display current logo' },
+      ],
+    })
+  );
+
+  if (action === 'generate') {
+    return promptGenerate();
+  }
+
+  // action === 'run'
+  const config = tryLoadConfig();
+  if (!config) {
+    p.log.error(
+      'No valid .shell-logo.json found in the current directory.\n' +
+        '  Run again and choose "Generate" to create one.'
+    );
+    p.outro('Done');
+    process.exit(1);
+  }
+
+  p.outro('Launching logo...');
+  return { action: 'run', config };
+}