mkctx 3.0.0 → 4.0.1

package/README.md

@@ -1,4 +1,4 @@
-<h1 align="center">mkctx - Make Context</h1>
+# mkctx - Make Context
 
 <p align="center">
   <picture>
@@ -8,62 +8,52 @@
   </picture>
 </p>
 
-<p align="center">
-  A powerful command-line tool that generates comprehensive markdown context files from your project code, perfect for AI prompts and code analysis.
-</p>
+A powerful command-line tool that generates comprehensive context files from your project code, perfect for AI prompts and code analysis.
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/mkctx"><img src="https://img.shields.io/npm/v/mkctx.svg" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/mkctx"><img src="https://img.shields.io/npm/dm/mkctx.svg" alt="npm downloads"></a>
-  <a href="https://github.com/pnkkzero/mkctx/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/mkctx.svg" alt="license"></a>
-</p>
+[![npm version](https://img.shields.io/npm/v/mkctx.svg)](https://www.npmjs.com/package/mkctx)
+[![npm downloads](https://img.shields.io/npm/dm/mkctx.svg)](https://www.npmjs.com/package/mkctx)
+[![license](https://img.shields.io/npm/l/mkctx.svg)](https://github.com/pnkkzero/mkctx/blob/main/LICENSE)
 
-## ✨ Features
+## Features
 
-- 🚀 **Multi-platform** - Works on Windows, macOS, and Linux
-- 📝 **Smart Ignoring** - Respects custom ignore patterns and common system files
-- ⚙️ **Configurable** - Customize source directories, output locations, and comments
-- 🎯 **AI-Friendly** - Outputs code in markdown format ideal for AI prompts
-- 🎨 **Syntax Highlighting** - Proper language detection for code blocks
-- 🔄 **Dynamic Mode** - Interactive path selection when needed
-- 📊 **Context Statistics** - Token estimation and file analysis
+- 🚀 **Multi-platform** — Works on Windows, macOS, and Linux
+- 📝 **Smart Ignoring** — Respects custom ignore patterns and common system files
+- ⚙️ **Configurable** — Customize source directories, output locations, and comments
+- ✏️ **Custom Naming** — Specify custom filenames for your outputs or use the default `context`
+- 🎯 **AI-Friendly** — Outputs code in markdown format ideal for AI prompts
+- 🎨 **Syntax Highlighting** — Proper language detection for code blocks
+- 🔄 **Dual Mode** — Interactive menu or fully non-interactive via CLI flags
+- 📊 **Context Statistics** — Token estimation and file analysis
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install -g mkctx
 ```
 
-### Requirements
+**Requirements:** Node.js 18.0+
 
-- **Node.js** 18.0+
+## Quick Start
 
-## 🚀 Quick Start
-
-### Interactive Mode (Recommended)
+### Interactive mode
 
 ```bash
 mkctx
 ```
 
-This opens an interactive menu where you can:
-1. Generate context from config file or dynamically
-2. View context statistics
-3. Save the context to a file
+Opens a menu where you can generate context, choose output formats, and save with a custom name.
 
-### Create Configuration File
+### Non-interactive mode (no prompts)
 
 ```bash
-mkctx config
+mkctx --src ./src --format md --name my-project
 ```
 
-### Show Help
+Pass flags directly and the tool runs to completion without asking anything.
 
-```bash
-mkctx help
-```
+## Usage
 
-## 📋 Usage
+### Interactive menu
 
 ```
 ╔════════════════════════════════════════╗
@@ -77,28 +67,67 @@ mkctx help
     ❌ Exit
 ```
 
-After generating context:
+After scanning, you choose a format and optionally a filename:
 
 ```
 📊 Context Summary:
    Files: 42
    Lines: 3,847
-   Size: 156.23 KB
-   Est. tokens: ~39,058
+   Size:  156.23 KB
 
-? What would you like to do with this context?
-  ❯ 💾 Save context to file
-    🔙 Back to main menu
-    ❌ Exit
+? Select output format:
+  ❯ 📦 All formats (MD, JSON, TOON, XML)
+    📝 Markdown (.md)
+    🔧 JSON (.json) - Simple array
+    🎒 TOON (.toon) - Token-optimized
+    📄 XML (.xml)
+
+? Enter a name for the output files: (context)
 ```
 
-## ⚙️ Configuration
+### CLI flags (non-interactive)
+
+When any of the following flags are passed, mkctx skips all prompts and runs directly.
 
-### Project Configuration (`mkctx.config.json`)
+| Flag                     | Alias | Description                       | Default   |
+| ------------------------ | ----- | --------------------------------- | --------- |
+| `--src <path>`           | `-s`  | Source directory to scan          | `.`       |
+| `--output <path>`        | `-o`  | Output directory                  | `./mkctx` |
+| `--format <fmt>`         | `-f`  | Output format (see below)         | `md`      |
+| `--name <filename>`      | `-n`  | Base name for output files        | `context` |
+| `--ignore <patterns>`    |       | Comma-separated ignore patterns   |           |
+| `--first-comment <text>` |       | Override the first comment header |           |
+| `--last-comment <text>`  |       | Override the last comment footer  |           |
+
+**Format values:** `md`, `json`, `toon`, `xml`, `all`, or comma-separated combinations.
+
+```bash
+# Single format
+mkctx --src ./src --format md
+
+# Multiple formats
+mkctx --src . --format md,json --name snapshot
+
+# All formats with custom output directory
+mkctx --src . --format all --name my-project --output ./docs
+
+# Using short aliases
+mkctx -s ./src -f toon -n snapshot
+
+# With extra ignore patterns
+mkctx --src ./app --format md --ignore "*.test.ts,__tests__/"
+
+# Using = syntax
+mkctx --src=./src --format=md,json --name=snapshot
+```
+
+## Configuration file
+
+Run `mkctx config` to create a `mkctx.config.json` in the current directory:
 
 ```json
 {
-  "src": "./src",
+  "src": ".",
   "ignore": "*.log, temp/, node_modules/, .git/, dist/, build/",
   "output": "./mkctx",
   "first_comment": "/* Project Context */",
@@ -106,127 +135,121 @@ After generating context:
 }
 ```
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `src` | Source directory to scan | `"."` |
-| `ignore` | Comma-separated patterns to ignore | See defaults |
-| `output` | Output directory for context file | `"./mkctx"` |
-| `first_comment` | Comment at the beginning | `"/* Project Context */"` |
-| `last_comment` | Comment at the end | `"/* End of Context */"` |
-
-## 🔧 CLI Options
-
-```bash
-mkctx                    # Interactive mode (recommended)
-mkctx config             # Create configuration file
-mkctx help               # Show help message
-mkctx version            # Show version
-```
+| Option          | Description                            | Default                   |
+| --------------- | -------------------------------------- | ------------------------- |
+| `src`           | Source directory to scan               | `"."`                     |
+| `ignore`        | Comma-separated patterns to ignore     | See defaults              |
+| `output`        | Output directory for context files     | `"./mkctx"`               |
+| `first_comment` | Comment at the beginning of the output | `"/* Project Context */"` |
+| `last_comment`  | Comment at the end of the output       | `"/* End of Context */"`  |
 
-## 📂 Ignore Patterns
+When a config file is present and CLI flags are also passed, the flags take priority over the file values.
 
-mkctx supports several pattern types:
+## Ignore patterns
 
-- **Wildcards**: `*.log`, `*.test.js`, `*.spec.ts`
-- **Directories**: `temp/`, `dist/`, `build/`
-- **Glob patterns**: `**/.cache/`, `**/node_modules/`
-- **Exact match**: `config.local.json`
+Supported pattern types:
 
-### Default System Ignores
+- **Wildcards:** `*.log`, `*.test.js`, `*.spec.ts`
+- **Directories:** `temp/`, `dist/`, `build/`
+- **Glob patterns:** `**/.cache/`, `**/node_modules/`
+- **Exact match:** `config.local.json`
 
-These are always ignored automatically:
+The following are always ignored automatically: `.git`, `.svn`, `.hg`, `node_modules`, `__pycache__`, `.DS_Store`, `Thumbs.db`, `.vscode`, `.idea`, binary files, images, and archives.
 
-- `.git`, `.svn`, `.hg`
-- `node_modules`, `__pycache__`
-- `.DS_Store`, `Thumbs.db`
-- `.vscode`, `.idea`
-- Binary files, images, archives
+## Output formats
 
-## 📄 Output Format
+| Format | Extension | Description                                             |
+| ------ | --------- | ------------------------------------------------------- |
+| `md`   | `.md`     | Markdown with fenced code blocks and project structure  |
+| `json` | `.json`   | Simple JSON array of file objects                       |
+| `toon` | `.toon`   | Token-Oriented Object Notation — compact, LLM-optimized |
+| `xml`  | `.xml`    | XML with CDATA sections                                 |
 
-The generated `context.md` file contains your project code:
+### Markdown output example
 
 ````markdown
-/* Project Context */
+/_ Project Context _/
 
 ## Project Structure
 
-```
+\```
 📁 src/
 📁 src/components/
-📁 src/utils/
 
 42 files total
-```
+\```
 
 ## Source Files
 
 ### src/index.ts
 
-```typescript
+\```typescript
 import { App } from './app';
-
 const app = new App();
 app.start();
-```
+\```
 
-### src/utils/helpers.ts
-
-```typescript
-export function helper() {
-  return true;
-}
-```
-
-/* End of Context */
+/_ End of Context _/
 ````
 
-## 🎨 Supported Languages
-
-mkctx automatically detects and applies proper syntax highlighting for:
-
-| Category | Extensions |
-|----------|------------|
-| **JavaScript/TypeScript** | `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs` |
-| **Python** | `.py`, `.pyw` |
-| **Go** | `.go` |
-| **Rust** | `.rs` |
-| **Java/Kotlin** | `.java`, `.kt`, `.scala` |
-| **C/C++** | `.c`, `.cpp`, `.h`, `.hpp` |
-| **PHP** | `.php` |
-| **Ruby** | `.rb`, `.rake` |
-| **Shell** | `.sh`, `.bash`, `.zsh`, `.ps1` |
-| **Web** | `.html`, `.css`, `.scss`, `.vue`, `.svelte` |
-| **Data** | `.json`, `.yaml`, `.yml`, `.xml`, `.toml` |
-| **And many more...** | `.sql`, `.graphql`, `.proto`, `.prisma`, `.sol` |
-
-## 💡 Use Cases
-
-- **🤖 AI Code Analysis** - Feed your codebase to ChatGPT, Claude, or other AI tools
-- **📚 Code Understanding** - Share project overview for quick understanding
-- **👥 Code Reviews** - Share project overview with reviewers
-- **🎓 Onboarding** - Help new developers understand the project
-- **📝 Documentation** - Generate a snapshot of your codebase
-
-## 🖥️ Platform Support
+### JSON output example
 
-| Platform | Status |
-|----------|--------|
-| **macOS** | ✅ Full support |
-| **Linux** | ✅ Full support |
-| **Windows** | ✅ Full support |
-
-## 🔧 Troubleshooting
-
-### Command Not Found
-
-If `mkctx` is not found after installation:
+```json
+[
+  {
+    "path": "src/index.ts",
+    "name": "index.ts",
+    "extension": "ts",
+    "language": "typescript",
+    "lines": 150,
+    "size": 4096,
+    "content": "..."
+  }
+]
+```
 
-1. Make sure npm global bin is in your PATH
-2. Try: `npm bin -g` to see where global packages are installed
+## Supported languages
+
+| Category                | Extensions                                      |
+| ----------------------- | ----------------------------------------------- |
+| JavaScript / TypeScript | `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs`    |
+| Python                  | `.py`, `.pyw`                                   |
+| Go                      | `.go`                                           |
+| Rust                    | `.rs`                                           |
+| Java / Kotlin           | `.java`, `.kt`, `.scala`                        |
+| C / C++                 | `.c`, `.cpp`, `.h`, `.hpp`                      |
+| PHP                     | `.php`                                          |
+| Ruby                    | `.rb`, `.rake`                                  |
+| Shell                   | `.sh`, `.bash`, `.zsh`, `.ps1`                  |
+| Web                     | `.html`, `.css`, `.scss`, `.vue`, `.svelte`     |
+| Data                    | `.json`, `.yaml`, `.yml`, `.xml`, `.toml`       |
+| Other                   | `.sql`, `.graphql`, `.proto`, `.prisma`, `.sol` |
+
+## Use cases
+
+- **AI code analysis** — Feed your codebase to ChatGPT, Claude, or other AI tools
+- **Code reviews** — Share a full project snapshot with reviewers
+- **Onboarding** — Help new developers get oriented quickly
+- **Documentation** — Generate a versioned snapshot of your codebase
+- **CI/CD pipelines** — Use non-interactive flags to automate context generation
+
+## Platform support
+
+| Platform | Status          |
+| -------- | --------------- |
+| macOS    | ✅ Full support |
+| Linux    | ✅ Full support |
+| Windows  | ✅ Full support |
+
+## Troubleshooting
+
+**Command not found after installation**
+
+1. Make sure the npm global bin directory is in your PATH
+2. Run `npm bin -g` to check where global packages are installed
 3. Restart your terminal
 
-### Permission Errors (Unix)
+**Permission errors on Unix**
 
 ```bash
 sudo npm install -g mkctx
@@ -234,34 +257,38 @@ sudo npm install -g mkctx
 
 Or fix npm permissions: https://docs.npmjs.com/resolving-eacces-permissions-errors
 
-## 📋 Changelog
+## Changelog
+
+### v5.0.0
+
+- ✨ Added non-interactive CLI flags (`--src`, `--format`, `--output`, `--name`, `--ignore`, etc.)
+- 🔤 Added short aliases (`-s`, `-o`, `-f`, `-n`)
+- 🔧 Support for `--key=value` syntax
+- ♻️ Internal refactor with clean code structure
+
+### v4.0.0
+
+- ✏️ Added interactive filename selection when saving (defaults to `context`)
+- 🎨 Improved UI/UX for the file saving workflow
 
 ### v3.0.0
 
 - 🎯 Simplified to focus on context generation
 - 🗑️ Removed Ollama chat integration
 - ⚡ Faster startup and smaller footprint
-- 🧹 Cleaner codebase
 
 ### v2.x
 
 - Ollama AI chat integration (removed in v3)
-- Interactive chat interface
 
 ### v1.x
 
 - Initial Go-based implementation
 
-## 🤝 Contributing
+## Contributing
 
-Contributions are welcome! Please feel free to submit pull requests or open issues.
+Contributions are welcome! Feel free to open issues or submit pull requests.
 
-## 📄 License
+## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
-
----
-
-<p align="center">
-  Made with ❤️ for developers who love AI-assisted coding
-</p>
+MIT License — see [LICENSE](LICENSE) for details.