feat: enhance snip stats command with JSON output and detailed metrics, refactoring its implementation into a dedicated file.

Author: Bharath-code

CHANGELOG.md

@@ -20,13 +20,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Pipe JSON as template values: `echo '{"host":"prod"}' | snip pipe deploy --json`
   - Stdin passthrough to snippet process
   - Zero-chrome output for composability
+- `snip stats --json` — machine-readable statistics output
 - `stdinData` support in exec engine for stdin passthrough to child processes
 - Pipeline integration row in comparison tables (README + docs site)
+- Codecov coverage badge in README
+- Demo screenshots in README (`snip_sc_1.png`, `snip_sc_2.png`)
 
 ### Changed
+- `snip stats` extracted to its own command file with brand-colored output, language bar chart, and top tags
+- Unified CLI color palette to brand orange `#ff4d00` across list, search, show, run, stats
 - README: added `snip pipe` to commands table, replaced "Pipe-Friendly" section with "Pipeline Mode", marked pipe as shipped in roadmap
 - docs/index.html: updated feature card to "Unix Pipeline Mode", added comparison row, bumped CLI commands count to 20+
-- CHANGELOG: restructured unreleased section
+- `jest.config.js`: added coverage config (collectCoverageFrom, thresholds, reporters)
+- `color_scheme.md`: rewritten to match actual unified brand palette
 
 ## [0.2.0] - 2026-02-27
 

README.md

@@ -110,7 +110,7 @@ snip doctor          # validates storage, editor, fzf, shell, gist
 | `snip mv <old> <new>` | Rename a snippet |
 | `snip cat <name>` | Print raw content to stdout |
 | `snip recent [n]` | Show last _n_ used snippets (default: 5) |
-| `snip stats` | Library statistics |
+| `snip stats` | Library statistics (`--json`, language chart, top tags) |
 | `snip grab <url>` | Import from URL or `github:user/repo/path` |
 | `snip fzf` | fzf search with live preview |
 

docs/GTM_PLAYBOOK.md

@@ -33,24 +33,42 @@ Every dev has commands they re-type. snip is the only CLI snippet manager with *
 #### Reddit Post Template (r/commandline)
 
 ```
-Title: I built "snip" — a terminal snippet manager that actually executes code across any language
+Title: I built "snip" — a CLI snippet manager that runs code in any language, not just shell
 
-I kept losing one-off deploy scripts, docker commands, and API calls in my shell
-history. So I built snip.
+I got tired of losing deploy scripts, docker commands, and one-off API calls
+in my shell history. So I built snip — it saves, searches, and executes
+code snippets directly from your terminal.
 
-What makes it different from pet/navi/aliases:
+What makes it different from pet/navi/shell aliases:
 
-- Runs snippets in any language (sh, python, js, ruby) — not just shell
-- Pipeline mode: `echo '{"host":"prod"}' | snip pipe deploy --json`
-- Dangerous command detection (warns on rm -rf, sudo)
-- Interactive TUI with syntax highlighting
-- Parameterized templates: `docker run {{image:ubuntu}} {{cmd:bash}}`
-- Zero config: `npm install -g snip-manager`
+• Runs any language — sh, python, js, ruby, php, perl (not just shell)
+• Pipeline mode: echo '{"host":"prod"}' | snip pipe deploy --json
+• Parameterized templates: docker run {{image:ubuntu}} {{cmd:bash}}
+• Dangerous command detection — warns on rm -rf, sudo, dd before running
+• Interactive TUI with syntax highlighting and split-pane preview
+• fzf integration with live preview pane
+• Shell aliases — eval "$(snip alias)" turns every snippet into a command
+• Ctrl+G shell widget — search and paste snippets inline without leaving your prompt
+• GitHub Gist sync — push/pull your library across machines
+• Health check — snip doctor verifies your entire setup
+• JSON + SQLite backends — start simple, scale when your library grows
+• 58 tests, 20+ commands, zero config
 
+Quick demo:
+
+  $ echo 'const os = require("os"); console.log(os.hostname())' | snip add sys-info --lang js
+  $ snip exec sys-info
+  → Bharaths-MacBook-Air.local
+
+  $ snip stats --json | jq .totalRuns
+  → 14
+
+Install: npm install -g snip-manager
 GitHub: https://github.com/Bharath-code/snip
-npm: https://npmjs.com/package/snip-manager
+Docs: https://bharath-code.github.io/snip/
 
-Would love feedback — especially on what commands you'd want.
+What workflow would you use this for? I'm curious what commands people
+lose the most.
 ```
 
 > [!IMPORTANT]
@@ -63,22 +81,27 @@ Would love feedback — especially on what commands you'd want.
 **Post on a Tuesday or Wednesday, 10 AM ET.** This is when Show HN gets the most traffic.
 
 ```
-Title: Show HN: Snip – Terminal snippet manager with multi-lang execution and unix pipelines
+Title: Show HN: Snip – CLI snippet manager with multi-lang execution and unix pipelines
 
 URL: https://github.com/Bharath-code/snip
 
 First comment (post immediately):
 
 Hi HN, I built snip because I kept losing deploy scripts and docker
 commands in my shell history. The existing tools (pet, navi) only run
-shell commands — snip runs JS, Python, Ruby, anything.
+shell — snip runs JS, Python, Ruby, anything.
 
-The feature I'm most proud of: `snip pipe`. You can pipe JSON into a
-snippet to fill template variables — makes it composable with CI/CD
-and unix pipelines.
+Key differentiators:
+- Pipeline mode: pipe JSON into snippets as template values
+- Parameterized templates with {{var:default}} syntax
+- Dangerous command detection (rm -rf, sudo, dd, fork bombs)
+- Interactive TUI with syntax highlighting (blessed)
+- fzf integration, Ctrl+G shell widget, shell aliases
+- GitHub Gist sync for cross-machine portability
+- JSON or SQLite storage, zero external services
 
-Built with Node.js, Commander.js, blessed for TUI, Fuse.js for fuzzy
-search. Zero external services, fully local-first.
+Tech stack: Node.js, Commander.js, Fuse.js (fuzzy search), blessed (TUI).
+58 tests, 20+ commands. Fully local-first, MIT license.
 
 npm install -g snip-manager
 
@@ -101,55 +124,63 @@ I built a terminal tool that replaces my 47 shell aliases.
 It runs snippets in any language, detects dangerous commands,
 and pipes JSON into templates.
 
-Open source, zero config.
+Open source. Zero config. 20+ commands.
 
 🧵 Here's what makes snip different:
 
 Tweet 2:
 The problem:
 → Aliases break across machines
-→ Shell history disappears  
+→ Shell history disappears
 → You can't run a Python snippet from a shell alias
 
 snip stores code snippets and runs them in their native language.
+JS, Python, Ruby, PHP — not just shell.
 
-`snip exec deploy-api`    ← runs immediately
-`snip run deploy-api`     ← previews first
+$ echo 'console.log(os.hostname())' | snip add sys-info --lang js
+$ snip exec sys-info
+→ my-macbook.local
 
 Tweet 3:
 The killer feature: pipeline mode.
 
 echo '{"host":"prod"}' | snip pipe deploy --json
 
 Pipe JSON → template variables get filled → snippet runs.
-
 No other snippet manager does this.
 
 Tweet 4:
 Safety built in:
 
-snip detects `rm -rf`, `sudo`, and destructive commands.
-Shows a warning before execution.
+snip detects rm -rf, sudo, dd, fork bombs, curl|bash,
+and 12 other destructive patterns.
+
+Shows a warning box before execution.
+You type "yes" to confirm — not just Enter.
 
 Because running the wrong deploy script at 3am shouldn't be easy.
 
 Tweet 5:
-Template variables with defaults:
-
-docker run {{image:ubuntu:24.04}} {{cmd:bash}}
+More features that ship out of the box:
 
-When you run the snippet, snip prompts for each variable.
-Defaults are pre-filled. Press Enter to accept.
+→ fzf with live preview pane
+→ Interactive TUI with syntax highlighting
+→ Ctrl+G shell widget (search inline)
+→ Shell aliases: eval "$(snip alias)"
+→ GitHub Gist sync across machines
+→ snip doctor health check
+→ JSON + SQLite backends
+→ snip stats --json for metrics
 
 Tweet 6:
-It's open source. MIT license.
+It's open source. MIT license. 58 tests.
 
 npm install -g snip-manager
 
 GitHub: github.com/Bharath-code/snip
-Website: bharath-code.github.io/snip/
+Docs: bharath-code.github.io/snip/
 
-I'd love your feedback — what commands do you wish existed?
+What commands do you lose the most? I'm building what you need.
 ```
 
 **Hashtags for discoverability:** `#cli` `#devtools` `#opensource` `#webdev` `#terminal`

lib/cli.js

@@ -187,32 +187,12 @@ program
   .option('--lang <lang>', 'Language (auto-detected if omitted)')
   .action((url, opts) => grabCmd(url, opts));
 
+const statsCmd = require('./commands/stats');
 program
   .command('stats')
   .description('Show snippet library statistics')
-  .action(() => {
-    const storage = require('./storage');
-    const all = storage.listSnippets();
-    const langMap = {};
-    let totalUsage = 0;
-    let mostUsed = null;
-    for (const s of all) {
-      const lang = s.language || 'unknown';
-      langMap[lang] = (langMap[lang] || 0) + 1;
-      totalUsage += s.usageCount || 0;
-      if (!mostUsed || (s.usageCount || 0) > (mostUsed.usageCount || 0)) mostUsed = s;
-    }
-    console.log(`\n  Snippets:  ${all.length}`);
-    console.log(`  Total runs: ${totalUsage}`);
-    if (mostUsed && mostUsed.usageCount) {
-      console.log(`  Most used:  ${mostUsed.name} (${mostUsed.usageCount} runs)`);
-    }
-    const langs = Object.entries(langMap).sort((a, b) => b[1] - a[1]);
-    if (langs.length) {
-      console.log(`  Languages:  ${langs.map(([l, c]) => `${l} (${c})`).join(', ')}`);
-    }
-    console.log('');
-  });
+  .option('--json', 'Output as JSON')
+  .action((opts) => statsCmd(opts));
 
 program
   .command('cp <source> <dest>')

lib/commands/stats.js

@@ -0,0 +1,90 @@
+/**
+ * snip stats — library statistics.
+ *
+ * Usage:
+ *   snip stats           # colored terminal output
+ *   snip stats --json    # machine-readable JSON
+ */
+
+const storage = require('../storage');
+
+// Brand-consistent colors (graceful fallback)
+let chalk = null;
+try {
+    const m = require('chalk');
+    chalk = (m && m.default) ? m.default : m;
+} catch (_) { }
+const c = {
+    accent: (t) => chalk ? chalk.hex('#ff4d00').bold(t) : t,
+    val: (t) => chalk ? chalk.hex('#ff7a33')(t) : t,
+    tag: (t) => chalk ? chalk.hex('#F5A623')(t) : t,
+    muted: (t) => chalk ? chalk.hex('#6C7086')(t) : t,
+    dim: (t) => chalk ? chalk.dim(t) : t,
+};
+
+function statsCmd(opts = {}) {
+    const all = storage.listSnippets();
+    const langMap = {};
+    const tagMap = {};
+    let totalUsage = 0;
+    let mostUsed = null;
+    let leastUsed = null;
+
+    for (const s of all) {
+        const lang = s.language || 'unknown';
+        langMap[lang] = (langMap[lang] || 0) + 1;
+        totalUsage += s.usageCount || 0;
+
+        for (const tag of (s.tags || [])) {
+            tagMap[tag] = (tagMap[tag] || 0) + 1;
+        }
+
+        if (!mostUsed || (s.usageCount || 0) > (mostUsed.usageCount || 0)) mostUsed = s;
+        if (!leastUsed || (s.usageCount || 0) < (leastUsed.usageCount || 0)) leastUsed = s;
+    }
+
+    const languages = Object.entries(langMap).sort((a, b) => b[1] - a[1]);
+    const topTags = Object.entries(tagMap).sort((a, b) => b[1] - a[1]).slice(0, 10);
+
+    // --json: machine-readable output
+    if (opts.json) {
+        console.log(JSON.stringify({
+            total: all.length,
+            totalRuns: totalUsage,
+            mostUsed: mostUsed && mostUsed.usageCount ? { name: mostUsed.name, runs: mostUsed.usageCount } : null,
+            languages: Object.fromEntries(languages),
+            topTags: Object.fromEntries(topTags),
+        }, null, 2));
+        return;
+    }
+
+    // Colored terminal output
+    console.log('');
+    console.log(c.accent('  ─── snip stats ───'));
+    console.log('');
+    console.log(`  Snippets     ${c.val(all.length)}`);
+    console.log(`  Total runs   ${c.val(totalUsage)}`);
+
+    if (mostUsed && mostUsed.usageCount) {
+        console.log(`  Most used    ${c.val(mostUsed.name)} ${c.muted(`(${mostUsed.usageCount} runs)`)}`);
+    }
+
+    if (languages.length) {
+        console.log('');
+        console.log(c.dim('  Languages'));
+        for (const [lang, count] of languages) {
+            const bar = '█'.repeat(Math.max(1, Math.round((count / all.length) * 20)));
+            console.log(`  ${c.val(lang.padEnd(14))} ${c.accent(bar)} ${c.muted(count)}`);
+        }
+    }
+
+    if (topTags.length) {
+        console.log('');
+        console.log(c.dim('  Top tags'));
+        console.log(`  ${topTags.map(([t, n]) => c.tag(`${t}(${n})`)).join('  ')}`);
+    }
+
+    console.log('');
+}
+
+module.exports = statsCmd;