feat: add new commands snip last and snip import-history, enhance snip stats with streak tracking, and improve command descriptions and completions

Author: Bharath-code

README.md

@@ -101,6 +101,7 @@ snip doctor          # validates storage, editor, fzf, shell, gist
 | `snip edit <name>` | Open in `$EDITOR` |
 | `snip rm <name>` | Delete (alias: `delete`) |
 | `snip update <name>` | Update metadata (`--tags`, `--lang`) |
+| `snip last` | Re-run the last executed snippet |
 
 ### Utilities
 
@@ -110,7 +111,8 @@ 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 (`--json`, language chart, top tags) |
+| `snip stats` | Library statistics (`--json`, language chart, top tags, `--streak`) |
+| `snip import-history` | Suggest commands from shell history (run 3+ times) |
 | `snip grab <url>` | Import from URL or `github:user/repo/path` |
 | `snip fzf` | fzf search with live preview |
 
@@ -126,6 +128,7 @@ snip doctor          # validates storage, editor, fzf, shell, gist
 | `snip doctor` | Health check |
 | `snip config <action>` | Get / set configuration |
 | `snip ui` | Interactive TUI |
+| `snip init` | Guided setup (editor, widget, example snippets, optional TUI) |
 
 ## Features
 

__tests__/search.test.js

@@ -2,10 +2,11 @@ const storage = require('../lib/storage');
 const search = require('../lib/search');
 
 describe('search', () => {
-  test('finds snippet content', () => {
-    const s = storage.addSnippet({ name: 'searchtest', content: 'unique-content-xyz123', language: 'txt', tags: ['u'] });
-    const results = search.search('xyz123', 200);
-    const ids = results.map(r => r.id);
-    expect(ids).toContain(s.id);
+  test('finds snippet by name and tags', () => {
+    const s = storage.addSnippet({ name: 'searchtest-foo', content: 'echo hello', language: 'txt', tags: ['uniquetag'] });
+    const byName = search.search('searchtest', 200);
+    const byTag = search.search('uniquetag', 200);
+    expect(byName.map(r => r.id)).toContain(s.id);
+    expect(byTag.map(r => r.id)).toContain(s.id);
   });
 });

completions/snip.bash

@@ -8,7 +8,7 @@ _snip_completions() {
   COMPREPLY=()
   cur="${COMP_WORDS[COMP_CWORD]}"
   prev="${COMP_WORDS[COMP_CWORD-1]}"
-  commands="add list search show run edit update rm delete export import sync ui config seed exec alias doctor cp mv cat recent fzf grab widget completion stats"
+  commands="add list search show run edit update rm delete export import sync ui config seed exec alias doctor init last import-history cp mv cat recent fzf grab widget completion stats"
 
   case "${prev}" in
     snip)

completions/snip.fish

@@ -20,6 +20,16 @@ complete -c snip -n "__fish_use_subcommand" -a "import" -d "Import snippets"
 complete -c snip -n "__fish_use_subcommand" -a "sync" -d "Sync with GitHub Gists"
 complete -c snip -n "__fish_use_subcommand" -a "ui" -d "Interactive TUI"
 complete -c snip -n "__fish_use_subcommand" -a "config" -d "View/modify config"
+complete -c snip -n "__fish_use_subcommand" -a "exec" -d "Execute snippet immediately"
+complete -c snip -n "__fish_use_subcommand" -a "pipe" -d "Pipeline mode (stdin→template→stdout)"
+complete -c snip -n "__fish_use_subcommand" -a "alias" -d "Generate shell aliases"
+complete -c snip -n "__fish_use_subcommand" -a "doctor" -d "Health check"
+complete -c snip -n "__fish_use_subcommand" -a "stats" -d "Library statistics"
+complete -c snip -n "__fish_use_subcommand" -a "recent" -d "Recently used snippets"
+complete -c snip -n "__fish_use_subcommand" -a "last" -d "Re-run last executed snippet"
+complete -c snip -n "__fish_use_subcommand" -a "init" -d "Guided setup"
+complete -c snip -n "__fish_use_subcommand" -a "grab" -d "Import from URL or GitHub"
+complete -c snip -n "__fish_use_subcommand" -a "import-history" -d "Suggest commands from shell history"
 
 # Options per subcommand
 complete -c snip -n "__fish_seen_subcommand_from add" -l lang -d "Language"
@@ -29,6 +39,11 @@ complete -c snip -n "__fish_seen_subcommand_from list" -l lang -d "Filter by lan
 complete -c snip -n "__fish_seen_subcommand_from list" -l sort -d "Sort order" -a "name usage recent"
 complete -c snip -n "__fish_seen_subcommand_from run" -l dry-run -d "Print without executing"
 complete -c snip -n "__fish_seen_subcommand_from run" -l confirm -d "Skip confirmation"
+complete -c snip -n "__fish_seen_subcommand_from stats" -l json -d "JSON output"
+complete -c snip -n "__fish_seen_subcommand_from stats" -l streak -d "Show usage streak"
+complete -c snip -n "__fish_seen_subcommand_from import-history" -l last -d "Analyze last N history lines"
+complete -c snip -n "__fish_seen_subcommand_from import-history" -l min-count -d "Minimum run count"
+complete -c snip -n "__fish_seen_subcommand_from import-history" -l json -d "JSON output"
 complete -c snip -n "__fish_seen_subcommand_from update" -l tags -d "Comma-separated tags"
 complete -c snip -n "__fish_seen_subcommand_from update" -l lang -d "Language"
 complete -c snip -n "__fish_seen_subcommand_from sync" -a "push pull"

docs/action_plan.md

@@ -25,8 +25,8 @@
 **Outcome:** ~900 kB lighter, 4 fewer deps.
 
 ### Medium
-- [ ] **1.5** Add Fuse index cache invalidation — only rebuild when snippet count or DB mtime changes (in `lib/search.js`).
-- [ ] **1.6** Lazy-load snippet content in `storage.js` — metadata-only for `list`/`search`; load content only for `show`/`run`/`exec`.
+- [x] **1.5** Add Fuse index cache invalidation — only rebuild when snippet count or DB mtime changes (in `lib/search.js`).
+- [x] **1.6** Lazy-load snippet content in `storage.js` — metadata-only for `list`/`search`; load content only for `show`/`run`/`exec`.
 
 ### Hard
 - [ ] **1.7** Add in-process cache for `listSnippets()` so repeated commands in same process don’t reload full data every time.
@@ -42,10 +42,10 @@
 - [ ] **2.4** Centralize `process.exit()` — move exit logic into `cli.js` where possible; commands should throw or return status.
 
 ### Medium
-- [ ] **2.5** 🔴 Add **file lock** (or single-writer) for JSON backend in `storage.js` so two concurrent `snip add` don’t corrupt the DB (e.g. lock file or mutex around read-modify-write).
+- [x] **2.5** 🔴 Add **file lock** (or single-writer) for JSON backend in `storage.js` so two concurrent `snip add` don’t corrupt the DB (e.g. lock file or mutex around read-modify-write).
 - [x] **2.6** 🔴 Add `better-sqlite3` as **optional dependency** in `package.json` and document; add `snip doctor` check that suggests `npm install -g better-sqlite3` when SQLite is enabled but module missing.
 - [ ] **2.7** Normalize error handling — all commands: errors to stderr, non-zero exit on failure, consistent behavior for scripting.
-- [ ] **2.8** Enforce `--no-color` / `NO_COLOR` everywhere — audit chalk usage and respect flag/env in all commands.
+- [x] **2.8** Enforce `--no-color` / `NO_COLOR` everywhere — audit chalk usage and respect flag/env in all commands.
 
 ### Hard
 - [ ] **2.9** Raise coverage — bring command-layer coverage up (add tests for add, run, grab, pipe, show, stats, alias, sync; aim 60%+ on critical paths).
@@ -63,9 +63,9 @@
 - [x] **3.4** **Gist errors** — On 401 from GitHub API, show: "Invalid GitHub token. Set SNIP_GIST_TOKEN with a valid PAT."
 
 ### Medium
-- [ ] **3.5** **`snip run` vs `snip exec`** — Clarify in docs and help text; consider merging or one-line explanation in `--help` and README.
-- [ ] **3.6** **Pager for long lists** — When `snip list` returns 50+ snippets, use a pager (e.g. `less`) or suggest TUI.
-- [ ] **3.7** TUI first-run — Show a tiny guide or overlay on first `snip ui` (e.g. keybindings, "? for help").
+- [x] **3.5** **`snip run` vs `snip exec`** — Clarify in docs and help text; consider merging or one-line explanation in `--help` and README.
+- [x] **3.6** **Pager for long lists** — When `snip list` returns 50+ snippets, use a pager (e.g. `less`) or suggest TUI.
+- [x] **3.7** TUI first-run — Show a tiny guide or overlay on first `snip ui` (e.g. keybindings, "? for help").
 
 ### Hard
 - [ ] **3.8** Add inline help overlay in TUI (e.g. `?` key) with keybindings and confirm behavior.
@@ -82,10 +82,10 @@
 - [ ] **4.5** **`snip config`** — Add basic validation (type checking / allowed keys) instead of accepting any value.
 
 ### Medium
-- [ ] **4.6** **`snip init`** — Single guided wizard: choose editor → set up shell widget → seed example snippets → optional "open TUI". Target: zero to aha in ~60 seconds.
-- [ ] **4.7** **`snip last`** — Re-run last executed snippet (store last snippet id/name; simple persistence).
-- [ ] **4.8** **`snip stats --streak`** — Days in a row using snip (needs lightweight usage tracking).
-- [ ] **4.9** **CLI help** — One-line example in `--help` for each core command; align README examples with behavior.
+- [x] **4.6** **`snip init`** — Single guided wizard: choose editor → set up shell widget → seed example snippets → optional "open TUI". Target: zero to aha in ~60 seconds.
+- [x] **4.7** **`snip last`** — Re-run last executed snippet (store last snippet id/name; simple persistence).
+- [x] **4.8** **`snip stats --streak`** — Days in a row using snip (needs lightweight usage tracking).
+- [x] **4.9** **CLI help** — One-line example in `--help` for each core command; align README examples with behavior.
 
 ### Hard
 - [ ] **4.10** **`snip watch <name>`** — Re-run snippet on file edit (watch snippet file or DB change).
@@ -102,8 +102,8 @@
 - [x] **5.4** **`snip config` validation** — Reject invalid values and list allowed keys/types in help.
 
 ### Medium
-- [ ] **5.5** **Shell history import** — `snip import-history --last 30`: analyze recent shell history, find commands run 3+ times, suggest saving as snippets.
-- [ ] **5.6** **Natural language search** — Make description first-class in search (e.g. higher weight in Fuse options) so "find my docker cleanup command" works well.
+- [x] **5.5** **Shell history import** — `snip import-history --last 30`: analyze recent shell history, find commands run 3+ times, suggest saving as snippets.
+- [x] **5.6** **Natural language search** — Make description first-class in search (e.g. higher weight in Fuse options) so "find my docker cleanup command" works well.
 
 ### Hard
 - [ ] **5.7** **Context-aware suggestions** — In dir with `package.json` → suggest npm snippets; with `Dockerfile` → suggest docker snippets (needs context detection + tagging or categories).

lib/cli.js

@@ -24,38 +24,38 @@ program.hook('preAction', () => {
 program
   .command('add <name>')
   .description('Add a new snippet')
-  .option('--lang <lang>')
-  .option('--tags <tags>')
+  .option('--lang <lang>', 'Language (sh, bash, python, etc.)')
+  .option('--tags <tags>', 'Comma-separated tags')
   .action((name, opts) => addCmd(name, opts));
 
 program
   .command('list')
   .description('List snippets')
-  .option('-t, --tag <tag>')
-  .option('--lang <lang>')
+  .option('-t, --tag <tag>', 'Filter by tag')
+  .option('--lang <lang>', 'Filter by language')
   .option('--sort <sort>', 'Sort by: name | usage | recent', 'name')
   .option('--limit <n>', 'Max items to show')
   .option('--json', 'Output as JSON')
   .action((opts) => listCmd(opts));
 
 program
   .command('search <query>')
-  .description('Fuzzy search snippets')
+  .description('Fuzzy search by name and tags')
   .option('--limit <n>', 'Max results (default: 15)')
   .option('--json', 'Output as JSON')
   .action((q, opts) => searchCmd(q, opts));
 
 program
   .command('show <idOrName>')
-  .description('Show snippet content')
+  .description('Show snippet content (use --raw to pipe)')
   .option('--edit', 'Open in editor')
   .option('--json', 'Output as JSON')
   .option('--raw', 'Print raw content (no header, for piping)')
   .action((idOrName, opts) => showCmd(idOrName, opts));
 
 program
   .command('run <idOrName>')
-  .description('Run a snippet (preview + confirm)')
+  .description('Run a snippet with preview and confirm (use exec for no prompt)')
   .option('--dry-run', 'Print but do not execute')
   .option('--confirm', 'Skip confirmation prompt (danger check still runs)')
   .action((idOrName, opts) => runCmd(idOrName, opts));
@@ -114,7 +114,7 @@ program
 const execCmd2 = require('./commands/exec');
 program
   .command('exec <idOrName>')
-  .description('Run a snippet immediately (no preview modal)')
+  .description('Run snippet immediately without preview (run = preview+confirm, exec = run now)')
   .option('--dry-run', 'Print but do not execute')
   .option('--force', 'Skip dangerous-command warning')
   .action((idOrName, opts) => execCmd2(idOrName, opts));
@@ -140,6 +140,12 @@ program
   .description('Health check — verify storage, editor, fzf, gist sync')
   .action(() => doctorCmd());
 
+const initCmd = require('./commands/init');
+program
+  .command('init')
+  .description('Guided setup: editor, widget, example snippets, optional TUI')
+  .action(() => initCmd());
+
 const fzfCmd = require('./commands/fzf');
 program
   .command('fzf')
@@ -192,8 +198,24 @@ program
   .command('stats')
   .description('Show snippet library statistics')
   .option('--json', 'Output as JSON')
+  .option('--streak', 'Show days-in-a-row usage streak')
   .action((opts) => statsCmd(opts));
 
+const lastCmd = require('./commands/last');
+program
+  .command('last')
+  .description('Re-run the last executed snippet')
+  .action(() => lastCmd());
+
+const importHistoryCmd = require('./commands/import-history');
+program
+  .command('import-history')
+  .description('Suggest commands from shell history run 3+ times')
+  .option('--last <n>', 'Analyze last N history lines', '500')
+  .option('--min-count <n>', 'Minimum run count to suggest', '3')
+  .option('--json', 'Output as JSON')
+  .action((opts) => importHistoryCmd(opts));
+
 program
   .command('cp <source> <dest>')
   .description('Duplicate a snippet')

lib/colors.js

@@ -1,11 +1,13 @@
 /**
  * Centralized color helpers — graceful fallback when chalk unavailable or NO_COLOR set.
  * Use this instead of defining chalk/colors in each command.
+ * Respects process.env.NO_COLOR and --no-color (set by cli.js preAction).
  */
 let chalk = null;
 try {
   const m = require('chalk');
   chalk = (m && m.default) ? m.default : m;
+  if (process.env.NO_COLOR) chalk = null;
 } catch (_) {}
 
 const c = {

lib/commands/exec.js

@@ -59,7 +59,11 @@ async function execCmd(idOrName, opts = {}) {
         language: snippet.language
     });
 
-    if (status === 0) storage.touchUsage(snippet);
+    if (status === 0) {
+      storage.touchUsage(snippet);
+      require('./last').setLastRun(snippet.id);
+      require('../streak').recordUsage();
+    }
     process.exitCode = status || 0;
 }
 

lib/commands/import-history.js

@@ -0,0 +1,79 @@
+/**
+ * snip import-history — analyze shell history and suggest commands run 3+ times.
+ * Usage: snip import-history [--last N] [--min-count M]
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { c } = require('../colors');
+
+const DEFAULT_LAST = 500;
+const MIN_COUNT = 3;
+const MIN_CMD_LEN = 4;
+
+function getHistoryPath() {
+  const histfile = process.env.HISTFILE;
+  if (histfile && fs.existsSync(histfile)) return histfile;
+  const shell = (process.env.SHELL || '').toLowerCase();
+  const home = os.homedir();
+  if (shell.includes('zsh')) return path.join(home, '.zsh_history');
+  if (shell.includes('bash')) return path.join(home, '.bash_history');
+  return path.join(home, '.zsh_history');
+}
+
+function parseZshLine(line) {
+  const m = line.match(/^: \d+:\d+;(.*)/);
+  return m ? m[1].trim() : line.trim();
+}
+
+function parseBashLine(line) {
+  return line.trim();
+}
+
+function importHistoryCmd(opts = {}) {
+  const last = Math.min(Math.max(1, parseInt(opts.last) || DEFAULT_LAST), 10000);
+  const minCount = Math.max(2, parseInt(opts.minCount) || MIN_COUNT);
+  const histPath = getHistoryPath();
+
+  if (!fs.existsSync(histPath)) {
+    console.error(`History file not found: ${histPath}`);
+    console.error('Set HISTFILE or use bash/zsh with default history path.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const raw = fs.readFileSync(histPath, 'utf8');
+  const isZsh = histPath.includes('zsh_history');
+  const lines = raw.split('\n').slice(-last).map(l => isZsh ? parseZshLine(l) : parseBashLine(l));
+  const countByCmd = {};
+  for (const line of lines) {
+    const cmd = line.trim();
+    if (cmd.length < MIN_CMD_LEN) continue;
+    countByCmd[cmd] = (countByCmd[cmd] || 0) + 1;
+  }
+  const suggested = Object.entries(countByCmd)
+    .filter(([, n]) => n >= minCount)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 30);
+
+  if (opts.json) {
+    console.log(JSON.stringify(suggested.map(([cmd, n]) => ({ command: cmd, count: n })), null, 2));
+    return;
+  }
+
+  if (suggested.length === 0) {
+    console.log(c.muted(`No commands run ${minCount}+ times in the last ${last} history lines.`));
+    console.log(c.dim('  Try --last 1000 or --min-count 2'));
+    return;
+  }
+
+  console.log(c.accent(`\n  Commands run ${minCount}+ times (from last ${last} history lines):\n`));
+  suggested.forEach(([cmd, n], i) => {
+    const preview = cmd.length > 60 ? cmd.slice(0, 57) + '…' : cmd;
+    console.log(`  ${(i + 1).toString().padStart(2)}. ${c.val(n + '×')} ${c.dim(preview)}`);
+  });
+  console.log(c.dim('\n  Add one: snip add <name> (then paste the command, or use snip grab)'));
+  console.log('');
+}
+
+module.exports = importHistoryCmd;