@nueldotdev/amnesiac 1.0.0

package/.npmignore

@@ -0,0 +1,24 @@
+# Ignore all files so that nothing is published to npm except what is explicitly whitelisted in package.json "files" or .npmignore negations
+
+*
+!.npmignore
+!bin/
+!lib/
+!package.json
+!README.md
+!LICENSE
+
+# Ignore config, test, and local files
+amnesiac.config.*
+.env
+.DS_Store
+node_modules/
+test/
+tests/
+coverage/
+.idea/
+.vscode/
+*.log
+*.local
+*.swp
+*.swo

package/README.md

@@ -0,0 +1,228 @@
+# Amnesiac
+
+Amnesiac is a CLI tool for keeping track of what’s changed in your code. It looks at your recent Git commits and diffs, uses Gemini to summarize them, and spits out a tidy, bullet-point for your changelog.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Configuration & Profiles](#configuration--profiles)
+  - [Configuration Loading Hierarchy](#configuration-loading-hierarchy)
+  - [Global Configuration (`~/.amnesiac/config.json`)](#global-configuration-amnesiacconfigjson)
+  - [Local Project Configuration (`amnesiac.config.js`)](#local-project-configuration-amnesiacconfigjs)
+- [Commands](#commands)
+  - [`amnesiac`](#amnesiac)
+  - [`amnesiac init`](#amnesiac-init)
+  - [`amnesiac config`](#amnesiac-config)
+  - [`amnesiac use <profile_name>`](#amnesiac-use-profile_name)
+  - [`amnesiac status`](#amnesiac-status)
+  - [`amnesiac reset`](#amnesiac-reset)
+  - [`amnesiac --version`](#amnesiac---version)
+- [API Key and Model Information](#api-key-and-model-information)
+  - [Getting Your API Key](#getting-your-api-key)
+  - [Keeping Your API Key Secure](#keeping-your-api-key-secure)
+  - [Understanding Gemini Models](#understanding-gemini-models)
+
+## Features
+
+- **Automated Changelog Generation:** Generate changelog entries from Git diffs and commit messages.
+- **Flexible Configuration:** Supports global profiles, local project-specific configurations, and CLI overrides.
+- **Profile Management:** Create, edit, list, and delete multiple configuration profiles.
+- **Active Profile Switching:** Easily switch between global profiles.
+- **Secure API Key Handling:** API key input is masked, and the status command redacts it.
+- **Intuitive CLI:** User-friendly commands for initialization, configuration, and status checks.
+
+## Installation
+
+To install Amnesiac, you will first need to have [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your system.
+
+Then, you can install Amnesiac globally via npm:
+
+```bash
+npm install -g amnesiac
+```
+
+This will make the `amnesiac` command available from any directory in your terminal.
+
+### Updating Amnesiac
+
+To update your globally installed Amnesiac to the latest version, simply run:
+
+```bash
+npm update -g amnesiac
+```
+
+## Getting Started
+
+1.  **Initialize your project (optional, but recommended for project-specific settings):**
+    ```bash
+    amnesiac init
+    ```
+    This command creates an `amnesiac.config.js` file in your project root with default settings.
+
+2.  **Configure your API Key and Model:**
+    Run `amnesiac config` to set up your global default profile or create a new one. You'll be prompted for your Gemini API key and preferred model.
+    ```bash
+    amnesiac config
+    ```
+    *(See [Configuration & Profiles](#configuration--profiles) for more details on managing profiles.)*
+
+3.  **Generate Changelog Entry:**
+    Once configured, you can generate a changelog entry by running:
+    ```bash
+    amnesiac
+    ```
+    This command will:
+    - Detect recent Git changes (staged, uncommitted, and committed).
+    - Send the diff to the Gemini API using your active configuration.
+    - Receive a concise changelog entry.
+    - Prepend the new entry to your `CHANGELOG.md` file (or the file specified in your config).
+
+## Configuration & Profiles
+
+Amnesiac offers a flexible configuration system that allows you to manage settings at different levels: per-project, globally, or as a one-off CLI override.
+
+### Configuration Loading Hierarchy
+
+Amnesiac loads configurations with the following priority (highest to lowest):
+
+1.  **CLI Overrides:** Options passed directly to the `amnesiac` command (e.g., `--use <profile>`, `--prompt <text>`, `--model <name>`). These are temporary for a single run.
+2.  **Local Project Configuration:** An `amnesiac.config.js` file in your current project's root directory. This takes precedence over your global active profile for that specific project.
+3.  **Global Active Profile:** The profile marked as `activeProfile` in your `~/.amnesiac/config.json` file. This is your default fallback.
+
+### Local Project Configuration (`amnesiac.config.js`)
+
+You can create an `amnesiac.config.js` file in the root of your project to define project-specific settings. This configuration will override your global active profile settings when you run `amnesiac` within that project, unless a `--use` flag is provided via CLI.
+
+**Example `amnesiac.config.js`:**
+
+```javascript
+export default {
+  apiKey: process.env.GEMINI_API_KEY, // Can be sourced from environment variables
+  model: "gemini-1.5-pro",
+  outputFile: "PROJECT_CHANGELOG.md",
+  prompt: `
+  Generate a comprehensive changelog entry focusing on new features and bug fixes for this project.
+  Include PR numbers if available.
+  `
+};
+```
+
+## Commands
+
+Amnesiac provides several commands to manage your configurations and generate changelogs.
+
+### `amnesiac`
+
+The main command to generate a changelog entry. It uses the configuration determined by the [loading hierarchy](#configuration-loading-hierarchy).
+
+**Usage:**
+```bash
+amnesiac
+amnesiac -p "Custom prompt for this run" # Override prompt for a single run
+amnesiac -m "gemini-pro" # Override model for a single run
+amnesiac -u work # Use 'work' profile for a single run
+```
+
+### `amnesiac init`
+
+Initializes a local `amnesiac.config.js` file in the current project directory with default settings. It will prompt for confirmation if the file already exists.
+
+**Usage:**
+```bash
+amnesiac init
+```
+
+### `amnesiac config`
+
+Manages your global Amnesiac profiles (stored in `~/.amnesiac/config.json`).
+
+**Usage:**
+
+-   **Set up or edit a profile (will prompt for details):**
+    ```bash
+    amnesiac config
+    amnesiac config --profile my-dev-profile # Directly specify a profile to create/edit
+    ```
+    When prompted for the API key, your input will be masked for security.
+
+-   **List all available profiles:**
+    ```bash
+    amnesiac config --list
+    # or
+    amnesiac config -l
+    ```
+    This will also indicate which profile is currently active.
+
+-   **Delete a specified profile:**
+    ```bash
+    amnesiac config --delete my-old-profile
+    # or
+    amnesiac config -d my-old-profile
+    ```
+
+### `amnesiac use <profile_name>`
+
+Sets the specified profile as the globally active profile in `~/.amnesiac/config.json`. This profile will be used by default for subsequent `amnesiac` runs unless overridden by a local config or CLI flag.
+
+**Usage:**
+```bash
+amnesiac use work
+amnesiac use personal
+```
+
+### `amnesiac status`
+
+Displays the currently active Amnesiac configuration, including the active profile, model, output file, and a snippet of the default prompt. The API key is masked for security.
+
+**Usage:**
+```bash
+amnesiac status
+```
+
+### `amnesiac reset`
+
+Deletes the entire global Amnesiac configuration file (`~/.amnesiac/config.json`), effectively removing all saved profiles and resetting global settings. This command requires user confirmation.
+
+**Usage:**
+```bash
+amnesiac reset
+```
+
+### `amnesiac --version`
+
+Displays the current version of the Amnesiac CLI tool.
+
+**Usage:**
+```bash
+amnesiac --version
+# or
+amnesiac -V
+```
+
+## API Key and Model Information
+
+### Getting Your API Key
+
+Amnesiac uses the Google Gemini API to generate changelog entries. You'll need an API key to use the tool.
+
+1.  Visit [Google AI Studio](https://aistudio.google.com/app/apikey).
+2.  Follow the instructions to create a new API key.
+3.  Once you have your key, you can configure it using `amnesiac config` or by setting it in your local `amnesiac.config.js` file or as an environment variable (e.g., `GEMINI_API_KEY`).
+
+### Keeping Your API Key Secure
+
+Your API key is a sensitive credential. Treat it like a password:
+-   **Do not commit it directly into your project's `amnesiac.config.js`** if the file is shared publicly. Instead, use environment variables (`process.env.GEMINI_API_KEY`) as shown in the local config example.
+-   When entering your API key via `amnesiac config`, the input is masked.
+-   When viewing your configuration with `amnesiac status`, the API key is partially masked.
+
+### Understanding Gemini Models
+
+The `model` parameter (e.g., `gemini-1.5-flash`, `gemini-1.5-pro`) determines which Gemini model Amnesiac uses for content generation.
+
+-   **`gemini-1.5-flash`:** A faster, more cost-effective model, suitable for many common tasks. This is the default.
+-   **`gemini-1.5-pro`:** A more capable model for complex tasks, offering higher quality but potentially at a higher latency or cost.
+
+You can specify the model in your global or local configurations, or override it for a single run using `amnesiac -m <model_name>`. Refer to the [Gemini API documentation](https://ai.google.dev/models/gemini) for the latest information on available models and their capabilities.

package/bin/cli.js

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import inquirer from "inquirer";
+import { generateDocs } from "../lib/doc_generator.js";
+import { loadConfig } from "../lib/config.js";
+import { readFileSync } from 'fs';
+
+const program = new Command();
+const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url)));
+
+// Handle Ctrl+C gracefully
+process.on('SIGINT', () => {
+  console.log('\nOperation cancelled by user.');
+  process.exit(1);
+});
+
+program.version(packageJson.version);
+
+program
+  .command("init")
+  .description("Initialize a local amnesiac.config.js file")
+  .action(async () => {
+    const localConfigPath = path.resolve(process.cwd(), "amnesiac.config.js");
+    const defaultConfigContent = `export default {
+  apiKey: process.env.GEMINI_API_KEY || "", // Consider adding a placeholder for API key
+  model: "gemini-1.5-flash",
+  outputFile: "CHANGELOG.md",
+  prompt: \`
+You are an assistant that generates clean, developer-friendly changelog entries.
+Summarize commit messages and diffs into concise bullet points.
+Output only valid markdown for a CHANGELOG.md file.
+\`
+};
+`;
+
+    if (fs.existsSync(localConfigPath)) {
+      const { overwrite } = await inquirer.prompt([
+        {
+          type: "confirm",
+          name: "overwrite",
+          message: "amnesiac.config.js already exists. Overwrite?",
+          default: false,
+        },
+      ]);
+      if (!overwrite) {
+        console.log("Initialization cancelled.");
+        return;
+      }
+    }
+
+    try {
+      fs.writeFileSync(localConfigPath, defaultConfigContent.trim());
+      console.log(`✅ Created amnesiac.config.js at ${localConfigPath}`);
+      console.log(`💡 Remember to add your Gemini API key to your environment variables (e.g., GEMINI_API_KEY=YOUR_KEY) or directly into amnesiac.config.js`);
+    } catch (error) {
+      console.error(`❌ Failed to create amnesiac.config.js: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("reset")
+  .description("Delete the global Amnesiac config file and all profiles")
+  .action(async () => {
+    const globalConfigPath = path.join(os.homedir(), ".amnesiac", "config.json");
+
+    if (!fs.existsSync(globalConfigPath)) {
+      console.log("🤷‍♀️ No global config file found to reset.");
+      return;
+    }
+
+    const { confirmReset } = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "confirmReset",
+        message: "This will delete your global Amnesiac config file (~/.amnesiac/config.json) and ALL saved profiles. Are you sure?",
+        default: false,
+      },
+    ]);
+
+    if (confirmReset) {
+      try {
+        fs.unlinkSync(globalConfigPath);
+        console.log("✅ Global Amnesiac config and all profiles have been reset.");
+      } catch (error) {
+        console.error("❌ Failed to delete global config file:", error.message);
+      }
+    } else {
+      console.log("Reset cancelled.");
+    }
+  });
+
+program
+  .command("status")
+  .description("Display the currently active Amnesiac configuration")
+  .action(async () => {
+    try {
+      const config = await loadConfig({}); // Load config without CLI overrides for status display
+
+      console.log("\n--- Amnesiac Configuration Status ---\n");
+      console.log(`Active Profile: ${config.activeProfile || 'N/A (using local/CLI defaults)'}`);
+      console.log(`API Key: ${config.apiKey ? '********' + config.apiKey.slice(-4) : 'Not Set'}`); // Mask API key
+      console.log(`Model: ${config.model}`);
+      console.log(`Output File: ${config.outputFile}`);
+      console.log(`Default Prompt: ${config.prompt.split('\n')[0]}...`); // Show first line of prompt
+      console.log("\n-------------------------------------\n");
+    } catch (error) {
+      console.error(`\n❌ An error occurred while fetching status: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("config")
+  .description("Set up or edit Amnesiac config")
+  .option("-p, --profile <name>", "Specify a profile name", "default")
+  .option("-l, --list", "List all available profiles")
+  .option("-d, --delete <name>", "Delete a specified profile")
+  .action(async (options) => {
+    try {
+      const dir = path.join(os.homedir(), ".amnesiac");
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir);
+
+      const globalConfigPath = path.join(dir, "config.json");
+      let globalConfig = { activeProfile: "default", profiles: {} };
+
+      if (fs.existsSync(globalConfigPath)) {
+        try {
+          globalConfig = JSON.parse(fs.readFileSync(globalConfigPath, "utf-8"));
+        } catch (e) {
+          console.error("❌ Error reading global config file. It might be corrupted. You can reset it with 'amnesiac reset'.", e.message);
+          // Continue with default empty config if file is corrupted, but alert user
+        }
+      }
+
+      if (options.list) {
+        console.log("Available profiles:");
+        const profiles = Object.keys(globalConfig.profiles);
+        if (profiles.length > 0) {
+          profiles.forEach(profile => {
+            const activeIndicator = profile === globalConfig.activeProfile ? " (active)" : "";
+            console.log(`- ${profile}${activeIndicator}`);
+          });
+        } else {
+          console.log("No profiles found.");
+        }
+        return; // Exit after listing profiles
+      }
+
+      if (options.delete) {
+        const profileToDelete = options.delete;
+        if (globalConfig.profiles[profileToDelete]) {
+          delete globalConfig.profiles[profileToDelete];
+          if (globalConfig.activeProfile === profileToDelete) {
+            globalConfig.activeProfile = "default"; // Reset active profile if deleted
+          }
+          fs.writeFileSync(globalConfigPath, JSON.stringify(globalConfig, null, 2));
+          console.log(`✅ Profile "${profileToDelete}" deleted successfully.`);
+        } else {
+          console.log(`❌ Profile "${profileToDelete}" not found.`);
+        }
+        return; // Exit after deleting profile
+      }
+
+      // Ask for profile name if not provided via flag
+      let profile = options.profile;
+      if (profile === 'default') {
+        const answers = await inquirer.prompt([
+          {
+            type: "input",
+            name: "profile",
+            message: "Profile name (default = 'default'):",
+            default: "default",
+          },
+        ]);
+        profile = answers.profile;
+      }
+
+      // Load existing profile config for editing
+      let existingConfig = globalConfig.profiles[profile] || {};
+      if (Object.keys(existingConfig).length > 0) {
+        console.log(`🔄 Editing existing profile "${profile}"...`);
+      } else {
+        console.log(`🆕 Creating new profile "${profile}"...`);
+      }
+
+      const answers = await inquirer.prompt([
+        {
+          type: "password",
+          name: "apiKey",
+          message: "Enter your API key:",
+          default: existingConfig.apiKey || "",
+          validate: (input) =>
+            input.trim() !== "" ? true : "API key is required.",
+        },
+        {
+          type: "input",
+          name: "model",
+          message: "Enter model name:",
+          default: existingConfig.model || "gemini-1.5-flash",
+        },
+        {
+          type: "input",
+          name: "prompt",
+          message: "Enter your default prompt (leave blank to use default):",
+          default:
+            existingConfig.prompt ||
+            "Generate a clear changelog entry for these changes.",
+        },
+        {
+          type: "input",
+          name: "outputFile",
+          message: "Enter output file name:",
+          default: existingConfig.outputFile || "CHANGELOG.md",
+        },
+      ]);
+
+      globalConfig.profiles[profile] = answers;
+      fs.writeFileSync(globalConfigPath, JSON.stringify(globalConfig, null, 2));
+      console.log(`✅ Config saved at ${globalConfigPath}`);
+    } catch (error) {
+      if (error.name === 'ExitPromptError') {
+        console.log('\nOperation cancelled by user.');
+        process.exit(1);
+      } else {
+        console.error(`\n❌ An unexpected error occurred during config: ${error.message}`);
+        process.exit(1);
+      }
+    }
+  });
+
+program
+  .command("use <profile_name>")
+  .description("Set the active profile for Amnesiac")
+  .action(async (profile_name) => {
+    const dir = path.join(os.homedir(), ".amnesiac");
+    const globalConfigPath = path.join(dir, "config.json");
+    let globalConfig = { activeProfile: "default", profiles: {} };
+
+    if (fs.existsSync(globalConfigPath)) {
+      try {
+        globalConfig = JSON.parse(fs.readFileSync(globalConfigPath, "utf-8"));
+      } catch (e) {
+        console.error("❌ Error reading global config file. It might be corrupted. You can reset it with 'amnesiac reset'.", e.message);
+        return; // Exit if global config is unreadable for 'use' command
+      }
+    }
+
+    if (globalConfig.profiles[profile_name]) {
+      globalConfig.activeProfile = profile_name;
+      fs.writeFileSync(globalConfigPath, JSON.stringify(globalConfig, null, 2));
+      console.log(`✅ Active profile set to "${profile_name}".`);
+    } else {
+      console.log(`❌ Profile "${profile_name}" not found. Please create it first using 'amnesiac config --profile ${profile_name}'.`);
+    }
+  });
+
+program
+  .option("-u, --use <profile>", "Use a specific profile for this run")
+  .option("-p, --prompt <text>", "Override prompt")
+  .option("-m, --model <name>", "Override model")
+  // Future: .option("-u, --use <profile>", "Use specific profile")
+  .action(async (opts) => {
+    try {
+      const config = await loadConfig(opts);
+      await generateDocs(config);
+    } catch (error) {
+      console.error(`\n❌ An error occurred: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nueldotdev/amnesiac",
+  "version": "1.0.0",
+  "description": "A command-line tool to automatically generate documentation for recent codebase changes using the Gemini API.",
+  "keywords": [
+    "cli-tool",
+    "documentation-generator",
+    "changelog",
+    "auto-docs",
+    "git-diff",
+    "git-integration",
+    "ai-powered",
+    "gemini-api",
+    "llm",
+    "google-ai",
+    "developer-tools",
+    "productivity"
+  ],
+  "homepage": "https://github.com/nueldotdev/amnesiac#readme",
+  "bugs": {
+    "url": "https://github.com/nueldotdev/amnesiac/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nueldotdev/amnesiac.git"
+  },
+  "license": "MIT",
+  "author": "nueldotdev",
+  "type": "module",
+  "bin": {
+    "amnesiac": "bin/cli.js"
+  },
+  "dependencies": {
+    "@google/generative-ai": "^0.24.1",
+    "commander": "^14.0.1",
+    "inquirer": "^12.9.6",
+    "simple-git": "^3.28.0"
+  }
+}