@adithya-naik/cmd-tracker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jatoth Adithya Naik
+
+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,187 @@
+<div align="center">
+
+# 📟 cmd-tracker
+
+### A developer tool that auto-captures, categorizes and saves terminal commands per project for easy revision
+
+[![npm version](https://img.shields.io/npm/v/@adithya-naik/cmd-tracker.svg)](https://www.npmjs.com/package/@adithya-naik/cmd-tracker)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-v14%2B-green.svg)](https://nodejs.org)
+
+</div>
+
+---
+
+## 🎯 What is cmd-tracker?
+
+**cmd-tracker** is an npm package that automatically captures, categorizes and saves every terminal command you type in a project.
+
+Perfect for:
+- 🎓 **Students** learning Linux, Git, Docker, Angular etc.
+- 👨‍💻 **Developers** who want to track commands used in a project
+- 📝 **Anyone** who wants to revise terminal commands they've used
+
+### How it works
+
+```
+You work normally in terminal
+         ↓
+Commands auto-captured in background
+         ↓
+Saved to .tracker/commands.json in your project
+         ↓
+Run tracker list → see entire command history
+```
+
+---
+
+## 📦 Installation
+
+Install in your learning/project repo:
+
+```bash
+npm install @adithya-naik/cmd-tracker
+```
+
+---
+
+## 🚀 Quick Start
+
+**Step 1 — Initialize in your repo:**
+```bash
+npx tracker init
+```
+
+**Step 2 — Enable automatic capture:**
+```bash
+npx tracker hook
+source ~/.bashrc  # or source ~/.zshrc on Mac
+```
+
+**Step 3 — Work normally! Then revise:**
+```bash
+npx tracker list
+```
+
+That's it! Every command you type is now saved automatically 🪄
+
+---
+
+## 📋 All Commands
+
+| Command | Description |
+|---|---|
+| `tracker init` | Initialize tracker in your project |
+| `tracker hook` | Enable automatic command capture |
+| `tracker unhook` | Disable automatic command capture |
+| `tracker list` | Show all saved commands |
+| `tracker list <category>` | Filter by category |
+| `tracker search <query>` | Search through commands |
+| `tracker stats` | Show statistics by category |
+| `tracker favorite <cmd>` | Toggle command as favorite |
+| `tracker favorites` | Show all favorites |
+| `tracker export` | Export as JSON |
+| `tracker export --csv` | Export as CSV (opens in Excel) |
+| `tracker clear` | Clear all commands |
+| `tracker clear <category>` | Clear specific category |
+
+---
+
+## 🗂️ Categories
+
+Commands are automatically categorized into:
+
+| Category | Commands |
+|---|---|
+| 🔀 `git` | git status, git push, git commit... |
+| 📦 `npm` | npm install, npx, npm run... |
+| 🐳 `docker` | docker ps, docker build... |
+| 🐧 `linux` | ls, cd, mkdir, chmod... |
+| 🟢 `node` | node, nodemon... |
+| 🔴 `angular` | ng new, ng serve, ng generate... |
+| 🐍 `python` | python, pip install... |
+| 📌 `others` | everything else |
+
+---
+
+## 💡 Usage Examples
+
+**Filter by category:**
+```bash
+tracker list git      # see all git commands
+tracker list linux    # see all linux commands
+tracker list npm      # see all npm commands
+```
+
+**Search commands:**
+```bash
+tracker search "install"   # find all install commands
+tracker search "git"       # find all git related commands
+```
+
+**Save favorites for quick revision:**
+```bash
+tracker favorite "git rebase -i HEAD~3"
+tracker favorites   # see all starred commands
+```
+
+**Export for sharing/backup:**
+```bash
+tracker export          # creates tracker-export.json
+tracker export --csv    # creates tracker-export.csv (opens in Excel!)
+```
+
+---
+
+## 📁 Project Structure
+
+After running `tracker init`, a `.tracker` folder is created:
+
+```
+your-project/
+├── .tracker/
+│   └── commands.json   ← your personal command history
+├── your-files...
+└── package.json
+```
+
+> ✅ `.tracker/` is automatically added to `.gitignore`
+> Your command history stays local — never pushed to GitHub
+
+---
+
+## 🖥️ Platform Support
+
+| Platform | Support |
+|---|---|
+| Mac (zsh) | ✅ Full support |
+| Linux (bash) | ✅ Full support |
+| Windows (Git Bash) | ✅ Supported |
+| Windows (PowerShell) | ⚠️ Manual save only |
+
+> Windows CMD/PowerShell users: use `tracker save "command"` manually
+> or use Git Bash / WSL for automatic capture
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Feel free to:
+- Open an issue for bugs or feature requests
+- Submit a pull request
+
+---
+
+## 📄 License
+
+MIT © [Jatoth Adithya Naik](https://github.com/adithya-naik)
+
+---
+
+<div align="center">
+
+⭐ **Star this repo if you find it useful!**
+
+[GitHub](https://github.com/adithya-naik/cmd-tracker) • [npm](https://www.npmjs.com/package/@adithya-naik/cmd-tracker) • [Issues](https://github.com/adithya-naik/cmd-tracker/issues)
+
+</div

package/bin/tracker.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+// "Hey! Run this file using Node.js"
+
+/*
+ * This is the ENTRY POINT of our CLI tool
+ * When user types "tracker" in terminal, this file runs first
+ * Think of it like the main gate of our entire application
+ */
+
+/*Current commands:
+ * tracker init        → sets up .tracker folder in user's repo
+ * tracker save <cmd>  → saves a command (called by shell hook)
+ *
+ * Coming soon:
+ * tracker list   → show all saved commands
+ * tracker stats  → show command statistics
+ * tracker search → search saved commands
+*/
+
+// Import commander - this package helps us build CLI commands easily
+// Like "list", "stats", "search" etc.
+const { program } = require("commander");
+
+// Import package.json to read our version number
+// __dirname = current folder path (bin/)
+// ../ = go one level up (to root of project)
+const packageJson = require("../package.json");
+
+/*
+ * Import our init command function
+ * This is the function that runs when user types: tracker init
+ *
+ * We import FROM src/commands/init.js
+ * bin/ → go up one level → ../
+ * then into src/commands/init.js
+ */
+const { initCommand } = require("../src/commands/init");
+
+/*
+ * Import our save command function
+ * This runs automatically via shell hook every time
+ * user types a command in terminal
+ */
+const { saveCommandAction } = require("../src/commands/save");
+// Import list command function
+const { listCommand } = require("../src/commands/list");
+// Import search command function
+const { searchCommand } = require("../src/commands/search");
+const { statsCommand } = require("../src/commands/stats");
+const { clearCommand } = require("../src/commands/clear");
+const { exportCommand } = require("../src/commands/export");
+const { hookCommand, unhookCommand } = require("../src/commands/hook");
+const { favoriteCommand, favoritesCommand } = require("../src/commands/favorite");
+/*
+ * .name() → sets the name of our CLI tool
+ * This shows up when user types: tracker --help
+ */
+program.name("tracker");
+
+/*
+ * .description() → explains what our tool does
+ * This also shows up in: tracker --help
+ */
+program.description("📟 A developer tool that auto-captures, categorizes and saves terminal commands per project for easy revision");
+
+/*
+ * .version() → sets the version of our CLI tool
+ * packageJson.version reads "1.0.0" from package.json
+ * So we never have to update version in two places
+ * User can check version by typing: tracker --version
+ */
+program.version(packageJson.version);
+
+// FIRST COMMAND
+
+/*
+ * .command() → defines a new CLI command
+ * "hello" → this is what user types after tracker
+ * So user runs: tracker hello
+ */
+program
+  .command("hello")
+
+  /*
+   * .description() → explains what this command does
+   * Shows up when user types: tracker --help
+   */
+  .description("A test command to check if CLI is working")
+
+  /*
+   * .action() → this function runs when user types: tracker hello
+   * Whatever code you write inside here — runs when command is called
+   */
+  .action(() => {
+    console.log("👋 Hey! tracker CLI is working perfectly!");
+    console.log("🚀 Let's start tracking your commands!");
+  });
+
+
+/*
+* Register the INIT command
+*
+* .command("init")  → user types: tracker init
+* .description()    → shows in tracker --help
+* .action()         → runs initCommand() when user types tracker init
+*
+* initCommand is imported from src/commands/init.js
+* We just CALL it here — all logic lives in init.js
+* This keeps bin/tracker.js clean and simple
+*/
+program
+  .command("init")
+  .description("Initialize cmd-tracker in your current project")
+  .action(() => {
+    initCommand();
+  });
+
+/*
+* Register the SAVE command
+*
+* This command is special — users never type it manually
+* It gets called automatically by the shell hook
+*
+* .argument("<command>") → accepts everything after "tracker save"
+* as a single string argument
+*
+* Example:
+* tracker save git status origin main
+* → command = "git status origin main"
+*
+* "<command>" → angle brackets mean this argument is REQUIRED
+* "[command]" → square brackets mean OPTIONAL
+*/
+program
+  .command("save")
+  .description("Save a command to tracker (called automatically by shell hook)")
+  .argument("<command>", "the terminal command to save")
+  .action((command) => {
+    saveCommandAction(command);
+  });
+
+/*
+* Register LIST command
+*
+* tracker list          → shows all commands
+* tracker list git      → shows only git commands
+*
+* [category] → square brackets = OPTIONAL argument
+*/
+program
+  .command("list")
+  .description("List all saved commands or filter by category")
+  .argument("[category]", "optional category filter (git/npm/docker/linux/node/angular/python/others)")
+  .action((category) => {
+    listCommand(category);
+  });
+
+/*
+* Register SEARCH command
+*
+* tracker search "git"     → finds commands containing "git"
+* tracker search "install" → finds commands containing "install"
+*
+* <query> → required argument
+*/
+program
+  .command("search")
+  .description("Search through all saved commands")
+  .argument("<query>", "search term to look for in saved commands")
+  .action((query) => {
+    searchCommand(query);
+  });
+
+/*
+* STATS command
+* tracker stats → shows category breakdown with percentages
+*/
+program
+  .command("stats")
+  .description("Show statistics of saved commands by category")
+  .action(() => {
+    statsCommand();
+  });
+
+/*
+ * CLEAR command
+ * tracker clear       → clears ALL commands (asks confirmation)
+ * tracker clear git   → clears only git commands (asks confirmation)
+ *
+ * [category] → optional argument
+ */
+program
+  .command("clear")
+  .description("Clear all saved commands or a specific category")
+  .argument("[category]", "optional category to clear")
+  .action((category) => {
+    clearCommand(category);
+  });
+
+/*
+ * EXPORT command
+ * tracker export       → exports as JSON file
+ * tracker export --csv → exports as CSV file
+ *
+ * .option() → adds an optional flag to a command
+ * "--csv" → user types --csv to trigger CSV export
+ */
+program
+  .command("export")
+  .description("Export saved commands as JSON or CSV file")
+  .option("--csv", "export as CSV instead of JSON")
+  .action((options) => {
+    exportCommand(options);
+  });
+
+/*
+* HOOK command
+* tracker hook → installs shell hook for auto capture
+*/
+program
+  .command("hook")
+  .description("Enable automatic command capture via shell hook")
+  .action(() => {
+    hookCommand();
+  });
+
+/*
+ * UNHOOK command
+ * tracker unhook → removes shell hook
+ */
+program
+  .command("unhook")
+  .description("Disable automatic command capture")
+  .action(() => {
+    unhookCommand();
+  });
+
+
+/*
+* FAVORITE command
+* tracker favorite "git status" → toggles favorite
+*/
+program
+  .command("favorite")
+  .description("Toggle a command as favorite")
+  .argument("<command>", "command to mark as favorite")
+  .action((command) => {
+    favoriteCommand(command);
+  });
+
+/*
+ * FAVORITES command
+ * tracker favorites → lists all favorites
+ */
+program
+  .command("favorites")
+  .description("List all favorited commands")
+  .action(() => {
+    favoritesCommand();
+  });
+/*
+ * This line is VERY important
+ * It tells commander to start reading what the user typed
+ * Without this line - nothing works
+ * Always keep this at the BOTTOM of this file *
+ * process.argv contains everything user typed:
+ * ["node", "tracker.js", "init"] → runs init command
+ * ["node", "tracker.js", "list"] → runs list command (coming soon)
+ */
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@adithya-naik/cmd-tracker",
+  "version": "1.0.0",
+  "description": "📟 A developer tool that auto-captures, categorizes and saves terminal commands per project for easy revision",
+  "main": "src/index.js",
+  "bin": {
+    "tracker": "bin/tracker.js"
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adithya-naik/cmd-tracker.git"
+  },
+  "keywords": [
+    "terminal",
+    "commands",
+    "tracker",
+    "cli",
+    "developer-tool",
+    "learning",
+    "revision",
+    "shell-hook",
+    "history",
+    "productivity"
+  ],
+  "author": "Jatoth Adithya Naik <jatothadithyanaik@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/adithya-naik/cmd-tracker/issues"
+  },
+  "homepage": "https://github.com/adithya-naik/cmd-tracker#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "chalk": "^4.1.2"
+  }
+}

package/src/commands/clear.js

@@ -0,0 +1,109 @@
+/*
+ * clear.js
+ * Now with proper error handling using validator.js
+ */
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const { readCommands } = require("../utils/storage");
+const {
+  isInitialized,
+  showInitError,
+  isValidCategory,
+  showCategoryError
+} = require("../utils/validator");
+
+const COMMANDS_FILE = path.join(process.cwd(), ".tracker", "commands.json");
+
+function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+async function clearCommand(category) {
+
+  /*
+   * Check initialization first
+   */
+  if (!isInitialized()) {
+    showInitError();
+    return;
+  }
+
+  /*
+   * Validate category if provided
+   */
+  if (category && !isValidCategory(category)) {
+    showCategoryError(category);
+    return;
+  }
+
+  try {
+    const data = readCommands();
+
+    if (category) {
+      const cat = category.toLowerCase();
+
+      if (data[cat].length === 0) {
+        console.log(`\n📭 No commands saved in ${cat}\n`);
+        return;
+      }
+
+      const answer = await ask(
+        `\n⚠️  Clear all ${data[cat].length} ${cat} commands? (yes/no): `
+      );
+
+      if (answer.toLowerCase() !== "yes") {
+        console.log("❌ Cancelled\n");
+        return;
+      }
+
+      data[cat] = [];
+      fs.writeFileSync(COMMANDS_FILE, JSON.stringify(data, null, 2));
+      console.log(`\n✅ Cleared all ${cat} commands\n`);
+      return;
+    }
+
+    const total = Object.values(data).reduce(
+      (sum, commands) => sum + commands.length, 0
+    );
+
+    if (total === 0) {
+      console.log("\n📭 No commands saved yet\n");
+      return;
+    }
+
+    const answer = await ask(
+      `\n⚠️  Clear ALL ${total} saved commands? This cannot be undone! (yes/no): `
+    );
+
+    if (answer.toLowerCase() !== "yes") {
+      console.log("❌ Cancelled\n");
+      return;
+    }
+
+    const emptyData = {
+      git: [], npm: [], docker: [], linux: [],
+      node: [], angular: [], python: [], others: []
+    };
+
+    fs.writeFileSync(COMMANDS_FILE, JSON.stringify(emptyData, null, 2));
+    console.log(`\n✅ Cleared all ${total} saved commands\n`);
+
+  } catch (error) {
+    console.log("\n❌ Error clearing commands");
+    console.log("💡 Try running tracker init again\n");
+  }
+}
+
+module.exports = { clearCommand };