shellrecap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 didrod205
+
+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,198 @@
+<div align="center">
+
+# ❯ shellrecap
+
+### Spotify Wrapped for your terminal — what does your shell history say about you?
+
+[![npm version](https://img.shields.io/npm/v/shellrecap.svg?color=success)](https://www.npmjs.com/package/shellrecap)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/shellrecap?label=core%20gzip)](https://bundlephobia.com/package/shellrecap)
+[![CI](https://github.com/didrod205/shellrecap/actions/workflows/ci.yml/badge.svg)](https://github.com/didrod205/shellrecap/actions/workflows/ci.yml)
+[![types](https://img.shields.io/npm/types/shellrecap.svg)](https://www.npmjs.com/package/shellrecap)
+[![license](https://img.shields.io/npm/l/shellrecap.svg)](./LICENSE)
+
+<img src="./examples/sample-card.png" width="420" alt="A shellrecap card: The Night Owl, 7,140 commands typed, git on top, peak hour 2 AM." />
+
+```bash
+npx shellrecap        # reads your shell history — and never uploads a byte of it
+```
+
+</div>
+
+You typed `git status` one thousand times this year. You retyped the same
+27-character `kubectl` incantation two hundred times instead of making an alias.
+You committed `gti status` to history 31 times. And somewhere in that file there
+may be a **token you once pasted into a command line**, sitting in plaintext.
+
+**shellrecap reads your `zsh`/`bash`/`fish` history and turns it into a recap** —
+your top commands, the hour you actually work, your typo hall of shame, the
+aliases you're owed (with exact keystrokes saved), and any secrets you've left
+in the file (**always masked**). A persona card sums you up, exportable as an SVG
+made for posting.
+
+Your shell history is full of paths, hostnames, and credentials — **the one file
+you should never paste into a website or a chatbot**. So shellrecap runs entirely
+on your machine: no hooks to install, no account, no network. It just reads the
+file your shell already writes.
+
+```
+  🦉  The Night Owl
+     Your terminal sees more moonlight than sunlight.
+
+  7,140 commands   ·   56 unique   ·   41 different programs
+
+  Top commands
+  git     ██████████████████████ 2,178
+  cd      ████████               761
+  ls      ███████                729
+
+  When you type  (peak 2 AM · Monday)
+  ▇██▆▁▁▁▁▁▂▃▃▃▃▃▃▃▃▃▆▆███
+
+  Typos  sl→ls ×86 · gti→git ×69 · cd..→cd .. ×48 · claer→clear ×39
+  316 mistyped commands · 1,145 wasted keystrokes
+
+  Aliases you're owed  (could have saved 48,031 keystrokes)
+  alias kgpp='kubectl get pods -n production'
+    typed 197× — saves 5,122 keystrokes
+
+  ⚠ 3 possible secrets in your history
+    ghp_FA… GitHub token — entry #546
+```
+
+## Why shellrecap?
+
+- 🎤 **The roast you can't get elsewhere.** GitHub has a wrapped. Spotify has a
+  wrapped. Your terminal — where you actually live — has nothing. Until now.
+- 🔒 **Built for the one file you must not upload.** No hooks, no daemon, no
+  account, no network calls. It reads `~/.zsh_history` (or bash/fish) locally and
+  computes everything in-process. The shareable card shows **only command names
+  and counts** — never full command lines, which can contain hostnames and paths.
+- 🎁 **It pays you back.** Alias suggestions are computed from what *you* actually
+  retype, ranked by exact keystrokes saved — copy-paste one line into your rc file.
+- 🧹 **It might save you an incident.** Tokens, AWS keys, `-p` passwords, and
+  inline `SECRET=` vars left in history are detected and reported **masked**, with
+  the entry number so you can delete the line.
+- 🧠 **Deterministic, zero-dependency core.** Same history → same recap. The pure
+  engine is browser-safe (a paste-and-see playground is on the roadmap).
+
+## Install
+
+```bash
+# run it now, no install
+npx shellrecap
+
+# or keep it around
+npm install -g shellrecap
+```
+
+Node ≥ 18. Works with **zsh** (plain & `EXTENDED_HISTORY`), **bash** (plain &
+`HISTTIMEFORMAT`), and **fish**. Time-of-day stats appear when your history has
+timestamps; everything else works regardless.
+
+## Quick start
+
+```bash
+shellrecap                          # auto-finds your history (most recent shell wins)
+shellrecap ~/.bash_history          # point at a specific file
+shellrecap --shell fish             # force a format
+shellrecap doctor                   # list the history files it can see (paths only)
+shellrecap report                   # write shellrecap.svg + .md + .json to share
+shellrecap report --theme candy     # tokyonight | dark | light | candy
+history | shellrecap --stdin        # pipe anything
+```
+
+## What it figures out
+
+| Group | What you get |
+| ----- | ------------ |
+| **Persona** | One of ten (🦉 Night Owl, 🧙 Pipe Wizard, 🔱 Sudo Summoner, 🐙 Git Gremlin, 🐳 Container Captain, 🧘 Vim Monk, 🎨 Typo Artist, 🧭 Navigator, 🌐 Polyglot, 🎛️ Steady Operator) — picked by deterministic rules |
+| **Top commands** | Programs and "favorite moves" (`git status`, `docker compose`…), pipe & sudo rates |
+| **Rhythm** | Commands by hour/weekday, peak hour, night-owl & weekend share, busiest day *(needs timestamps)* |
+| **Typos** | Curated classics (`gti`, `sl`, `claer`…) plus edit-distance detection against your own top commands — with wasted-keystroke totals |
+| **Aliases you're owed** | Exact long commands you retype, suggested alias names, keystrokes each would save |
+| **Secrets** | GitHub/AWS/Slack/Stripe/npm tokens, JWTs, `-p` passwords, inline `SECRET=` vars — **always masked**, with the entry number to delete |
+
+## Real scenarios
+
+**1. Post your card.** Run `shellrecap report`, open the SVG, screenshot, post.
+The card carries only command names and counts — safe by construction.
+
+**2. Actually fix your workflow.** Paste the top alias suggestion into your
+`.zshrc` and stop retyping that 30-character `kubectl` line 200 times a year:
+
+```bash
+shellrecap | grep "alias "   # → alias kgpp='kubectl get pods -n production'
+```
+
+**3. Audit your history for leaked credentials.** CI keys get pasted into
+terminals more often than anyone admits:
+
+```bash
+shellrecap --quiet --json recap.json   # secrets[] lists kind + entry number, masked
+```
+
+## Configuration
+
+`shellrecap init` writes `shellrecap.config.json`:
+
+```jsonc
+{
+  "theme": "tokyonight",     // card theme
+  "top": 8,                   // how many top commands / suggestions
+  "aliasMinCount": 10,        // suggest an alias after this many repeats
+  "aliasMinLength": 12,       // …for commands at least this long
+  "ignoreCommands": [],       // base commands to exclude entirely
+  "secretScan": true          // set false to skip the secret check
+}
+```
+
+Flags override config. `--tz <minutes>` pins the timezone for reproducible time
+stats (defaults to this machine's offset).
+
+## Library API
+
+The core is pure and browser-safe — feed it history text from anywhere:
+
+```ts
+import { parseHistory, analyze, renderCard, DEFAULT_CONFIG } from "shellrecap";
+
+const { entries, format } = parseHistory(rawHistoryText);
+const report = analyze(entries, DEFAULT_CONFIG, {
+  sourceLabel: "~/.zsh_history",
+  format,
+  tzOffsetMin: 540,
+});
+
+console.log(report.persona.title, report.aliases.totalSavable);
+const svg = renderCard(report, "tokyonight");
+```
+
+## Privacy, precisely
+
+- Reads your history file(s) **read-only**, locally. No network code exists in
+  this package — grep `dist/` if you like.
+- The terminal output may show full command lines (it stays in your terminal).
+- The **SVG card and Markdown/JSON exports never include full command lines or
+  secret values** — commands appear as names + counts, secrets only as masked
+  previews (`ghp_FA…`).
+
+## Roadmap
+
+- 🌐 **Browser playground** — paste history, see your card, 100% client-side
+  (the engine already runs in a browser).
+- 🐚 Atuin (SQLite) and PowerShell (`ConsoleHost_history.txt`) support.
+- 📊 Multi-file merge (zsh + bash on the same machine).
+- 🤖 **Optional `--ai` layer (bring-your-own key)** for a written "year in your
+  terminal" paragraph. The core stays 100% offline and deterministic.
+
+## 💖 Sponsor
+
+shellrecap is free and MIT-licensed, built in spare time. If it made you laugh,
+saved you keystrokes, or caught a leaked token:
+
+- ⭐ **Star this repo** — the simplest free way to help others find it.
+- 🍋 **[Sponsor via Lemon Squeezy](https://elab-studio.lemonsqueezy.com/checkout/buy/5d059b89-51d0-456b-b33a-ed56994f7010)** — one-time or recurring.
+
+## License
+
+[MIT](./LICENSE) © shellrecap contributors