kodu 1.2.0 → 2.0.1

package/AGENTS.md

@@ -4,11 +4,10 @@ This file provides guidelines and instructions for AI assistants working on the
 
 ## 1. Project Overview
 
-**Kodu** is a high-performance CLI utility that bridges local development environments with LLMs. It automates context preparation, code cleaning, reviews, and commit drafting.
+**Kodu** is a high-performance CLI utility that bridges local development environments with LLMs. It automates context preparation and code cleaning.
 
 - **Key Goals:** Speed (<0.5s startup), Determinism (no AI for critical file ops), DX (Developer Experience)
-- **Current Phase:** Phase 4 - AI Integration with Mastra/Git
-- **Available Commands:** `init`, `pack`, `clean`, `review`, `commit`, `ops`
+- **Available Commands:** `pack`, `clean`
 
 ## 2. Technology Stack (Enforced)
 
@@ -18,10 +17,8 @@ This file provides guidelines and instructions for AI assistants working on the
 | File System | node:fs/promises + tinyglobby | fs-extra, glob, rimraf |
 | Config | lilconfig | cosmiconfig, rc |
 | Validation | zod | class-validator, joi |
-| Process/Git | execa | child_process, shelljs |
 | CLI UI | @inquirer/prompts + picocolors | inquirer (legacy), chalk |
 | Spinners | yocto-spinner | ora, cli-spinners |
-| AI Agent | mastra | Direct openai SDK |
 | AST/Parsing | ts-morph | Regex, babel |
 | Tokens | js-tiktoken | gpt-3-encoder |
 | Clipboard | clipboardy | Native APIs |
@@ -39,16 +36,10 @@ src/
 ├── shared/                 # Shared Business Logic
 │   ├── tokenizer/          # TokenizerModule
 │   ├── git/                # GitModule
-│   ├── ai/                 # AiModule (Mastra)
 │   └── cleaner/            # CleanerService (AST)
-│   └── ssh/                # SshModule (remote ops via SSH)
 └── commands/               # Feature Commands
-    ├── init/               # kodu init
     ├── pack/               # kodu pack
-    ├── clean/              # kodu clean
-    ├── review/             # kodu review
-    ├── commit/             # kodu commit
-    └── ops/                # kodu ops <subcommand>
+    └── clean/              # kodu clean
 ```
 
 ## 4. Build, Lint & Test Commands
@@ -70,26 +61,6 @@ npm run lint:fix           # Biome with auto-fix
 
 # Full check (required before commit)
 npm run check              # TypeCheck + Biome + Knip
-
-# Run tests (if configured)
-npm test                   # Run all tests
-npm test -- <pattern>      # Run tests matching pattern
-npm test -- --testPathPattern=<pattern>  # Alternative
-```
-
-### Running a Single Test
-```bash
-# By file name
-npm test -- filename
-
-# By pattern
-npm test -- --testNamePattern="test name"
-
-# Watch mode
-npm test -- --watch
-
-# With coverage
-npm test -- --coverage
 ```
 
 ## 5. Code Style Guidelines
@@ -136,10 +107,6 @@ npm test -- --coverage
 
 ```json
 {
-  "llm": {
-    "model": "openai/gpt-4o",
-    "apiKeyEnv": "OPENAI_API_KEY"
-  },
   "cleaner": {
     "whitelist": ["//!"],
     "keepJSDoc": true,
@@ -148,48 +115,50 @@ npm test -- --coverage
   "packer": {
     "ignore": ["*.lock", "node_modules", "dist"],
     "useGitignore": true
-  },
-  "ops": {
-    "servers": {
-      "dev": {
-        "host": "example.com",
-        "port": 22,
-        "user": "ubuntu",
-        "sshKeyPath": "~/.ssh/id_rsa",
-        "paths": {
-          "apps": "/var/agent-apps",
-          "caddy": "/var/agent-apps/caddy"
-        }
-      }
-    }
   }
 }
 ```
 
-- Model format: `provider/model-name` (e.g., `openai/gpt-4o`, `anthropic/claude-4-5-sonnet`)
-- API keys from env vars only (never store in config)
 - Config validated via Zod on startup
+- `kodu.json` must be in current working directory
 
 ## 7. Commands Reference
 
-| Command | Description | Key Options |
-|---------|-------------|-------------|
-| `kodu init` | Interactive setup wizard | - |
-| `kodu pack` | Bundle files for LLM | `--copy`, `--template`, `--out` |
-| `kodu clean` | Remove comments (AST-based) | `--dry-run` |
-| `kodu review` | AI code review | `--mode`, `--ci`, `--output` |
-| `kodu commit` | Generate commit message | `--ci`, `--output` |
-| `kodu ops` | Remote server operations over SSH (JSON-only) | `sysinfo`, `env`, `routes`, `service` |
+### `kodu init`
+
+Add `.kodu/context.txt` to `.gitignore` (if `.gitignore` exists). Run once after cloning or setting up a project.
+
+### `kodu pack`
+
+Bundle project files into a single context file for LLMs.
+
+| Option | Description |
+|--------|-------------|
+| `-c, --copy` | Copy result to clipboard |
+| `-o, --out <path>` | Path to save result (default: `.kodu/context.txt`) |
+| `-p, --path <path>` | Directory or glob to include (repeatable) |
+| `-e, --exclude <pattern>` | Additional exclude pattern (repeatable) |
+| `-l, --list` | Print file list only, without content |
+| `-f, --format <format>` | Output format: `xml` (default) or `text` |
+| `-t, --template <name>` | Template name from `.kodu/prompts` |
+
+Output format `xml` wraps each file in `<file path="...">` tags — recommended for LLM consumption. Format `text` uses `// file: ...` header comments.
+
+### `kodu clean`
+
+Remove comments from source files using AST-based parsing (deterministic, no AI).
+
+| Option | Description |
+|--------|-------------|
+| `-d, --dry-run` | Show what will be removed without modifying files |
+| `-c, --changed` | Clean only git-changed files |
 
 ## 8. Critical Constraints
 
-1. **No AI in Cleaner:** `clean` command is deterministic (AST-based), never AI-generated
+1. **No AI:** Both commands are deterministic — no AI integration
 2. **Validation First:** Invalid `kodu.json` causes graceful crash with Zod error
-3. **Secrets:** Never commit secrets. API keys from env vars only
-4. **Performance:** Mindful of import costs. Use lightweight libraries
-5. **Git Preconditions:** AI commands require git repo with staged changes
-6. **Config Location:** `kodu.json` must be in current working directory
-7. **AgentOps Output Contract:** `kodu ops` commands must return strict JSON (no spinners/colors/prompts)
+3. **Performance:** Mindful of import costs. Use lightweight libraries
+4. **Config Location:** `kodu.json` must be in current working directory
 
 ## 9. Development Workflow
 
@@ -199,7 +168,7 @@ npm test -- --coverage
 3. Implement `run()` extending `CommandRunner`
 4. Decorate with `@Command()` from `nest-commander`
 5. Register module in `app.module.ts`
-6. Test: `npm run build && node dist/main.js <name>`
+6. Test: `npm run build && node dist/src/main.js <name>`
 
 ### Before Commit
 Always run:
@@ -214,7 +183,6 @@ This executes: TypeScript check + Biome lint + Knip dead code detection.
 - **Primary Gate:** Static analysis (TypeScript + Biome + Knip)
 - **No Legacy Tests:** Project relies on strict static typing
 - If tests exist: place in `__tests__/` or `*.test.ts` files
-- Use Vitest or Jest (check package.json for actual test runner)
 
 ## 11. Handling Uncertainties
 

package/README.md

@@ -1,171 +1,203 @@
 <div align="center">
 
-# Kodu 🦄
+# Kodu
 
-**The AI-First CLI for Modern Developers**
-
-Generate contexts, clean code, review PRs, draft commits, and run remote ops—instantly.
+**Bundle your codebase for LLMs. Strip noise. Ship faster.**
 
 [![npm version](https://img.shields.io/npm/v/kodu?style=flat-square&color=black)](https://www.npmjs.com/package/kodu)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square&color=black)](LICENSE)
-[![Privacy](https://img.shields.io/badge/Privacy-First-green.svg?style=flat-square)](https://github.com/uxname/kodu)
 
 </div>
 
 ---
 
-## ⚡ The Problem vs. Kodu
+## What it does
 
-| You (Manual) ❌ | Kodu (Automated) ✅ |
+| Problem | Kodu |
 | :--- | :--- |
-| Copy-pasting 10 files one by one | **`kodu pack`** bundles context in 1 click |
-| Hitting token limits with comments | **`kodu clean`** strips noise deterministically |
-| Context switching for code reviews | **`kodu review`** checks logic inside your terminal |
-| Writing boring commit messages | **`kodu commit`** generates semantic git messages |
-| SSHing around servers manually | **`kodu ops`** runs machine-readable remote operations |
+| Copy-pasting files one by one into ChatGPT | `kodu pack` bundles your entire project in one command |
+| Hitting token limits with comments and docs | `kodu clean` strips comments deterministically via AST |
 
 ---
 
-## 🚀 Instant Start
-
-Don't want to install? Run it directly:
+## Install
 
 ```bash
-# 1. Initialize config (creates kodu.json)
-npx kodu init
-
-# 2. Bundle your project to clipboard
-npx kodu pack --copy
+npm install -g kodu
 ```
 
-**Or install globally for speed (<0.5s startup):**
+Or run without installing:
 
 ```bash
-npm install -g kodu
+npx kodu pack --copy
 ```
 
 ---
 
-## 🛡️ Privacy & Security
+## kodu init
 
-We know trust is paramount when dealing with code.
+Add `.kodu/context.txt` to `.gitignore` so generated context files are never committed:
 
-*   **Local Execution:** Code analysis runs locally.
-*   **Zero Data Retention:** We don't store your code.
-*   **Explicit Control:** `.env`, `node_modules`, and lockfiles are ignored by default.
-*   **You Own the Keys:** Your API key (`OPENAI_API_KEY`) goes directly to the provider.
+```bash
+kodu init
+```
+
+Run once after cloning or setting up the project.
 
 ---
 
-## 💡 Common Workflows
+## kodu pack
 
-### 1. "I need to ask ChatGPT about my project"
-Pack your entire source code (minus ignored files) into the clipboard, optimized for tokens.
+Bundle project files into a single context file optimized for LLMs.
 
 ```bash
+# Pack everything and copy to clipboard
 kodu pack --copy
-# Output: Copied 45 files (12k tokens) to clipboard. Paste into ChatGPT!
-```
 
-### 2. "I want to save money on API costs"
-Strip comments and docs to reduce token count by ~30% before sending.
+# Pack only specific directories
+kodu pack --path src --path tests --copy
 
-```bash
-# Preview savings
-kodu clean --dry-run
+# Just see what files would be included
+kodu pack --list
 
-# Clean only what you changed (Great for PRs)
-kodu clean --changed
+# Exclude extra patterns on the fly
+kodu pack --exclude "**/*.test.ts" --exclude "docs/" --copy
+
+# Save to a custom path
+kodu pack --out /tmp/context.txt
+
+# Use plain text format instead of XML
+kodu pack --format text --copy
 ```
 
-### 3. "Check my code before I push"
-Get an AI review of your **staged** changes without leaving the terminal.
+### Output format
 
-```bash
-# Detect bugs and logical errors
-kodu review --mode bug
+By default, kodu wraps each file in XML tags — the format that LLMs parse most reliably:
+
+```xml
+<files>
+<file path="src/index.ts">
+// your code here
+</file>
 
-# Check for security leaks
-kodu review --mode security
+<file path="src/utils.ts">
+// more code
+</file>
+</files>
 ```
 
-### 4. "I need my agent to inspect a server"
-Run remote diagnostics and operations via `kodu ops` with strict JSON output.
+Use `--format text` for legacy `// file: path` style headers.
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-c, --copy` | Copy result to clipboard |
+| `-o, --out <path>` | Output file path (default: `.kodu/context.txt`) |
+| `-p, --path <path>` | Include only this directory/glob (repeatable) |
+| `-e, --exclude <pattern>` | Additional exclude pattern (repeatable) |
+| `-l, --list` | Print file list only, no content |
+| `-f, --format <xml\|text>` | Output format (default: `xml`) |
+| `--clean` | Strip comments in-memory before packing (files not modified) |
+| `-t, --template <name>` | Wrap output in a prompt template from `.kodu/prompts/` |
+
+---
+
+## kodu clean
+
+Remove comments from source files using AST-based parsing. No AI, fully deterministic.
 
 ```bash
-# Server health snapshot
-kodu ops sysinfo dev
+# Preview what would be removed (with byte/token savings)
+kodu clean --dry-run
 
-# Manage app env vars remotely
-kodu ops env dev set my-app --key NODE_ENV --val production
+# Show every removed comment, not just first 3
+kodu clean --dry-run --verbose
 
-# Read Caddy routes (raw Caddyfile)
-kodu ops routes dev list
+# Clean only git-staged files
+kodu clean --staged
+
+# Clean only git-changed files (staged + unstaged + untracked)
+kodu clean --changed
+
+# Target specific files or directories
+kodu clean src/utils.ts src/helpers/
+
+# Remove JSDoc too (overrides config)
+kodu clean --no-jsdoc
+
+# Backup originals before modifying
+kodu clean --backup
+
+# Read from stdin, write to stdout (great for scripting)
+cat src/foo.ts | kodu clean --stdin
+
+# Clean all project files
+kodu clean
 ```
 
----
+Supports `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.html`. Respects `cleaner.whitelist` in `kodu.json` (e.g. `//!` to preserve important comments).
+
+### Options
 
-## ⚙️ Configuration
+| Flag | Description |
+|------|-------------|
+| `-d, --dry-run` | Show what will be removed without modifying files |
+| `-v, --verbose` | Show all removed comments in dry-run (not just first 3) |
+| `-c, --changed` | Clean only git-changed files (staged + unstaged + untracked) |
+| `-s, --staged` | Clean only git-staged files |
+| `-n, --no-jsdoc` | Remove JSDoc comments (overrides `keepJSDoc` in config) |
+| `-b, --backup` | Save originals to `.kodu/backup/` before modifying |
+| `--stdin` | Read from stdin, write cleaned result to stdout |
 
-Kodu creates a `kodu.json` in your root. It's pre-configured, but fully hackable.
+---
+
+## Configuration
 
-<details>
-<summary><b>Click to see example configuration</b></summary>
+Create `kodu.json` in your project root:
 
 ```json
 {
-  "llm": {
-    "model": "openai/gpt-4o",
-    "apiKeyEnv": "OPENAI_API_KEY"
-  },
   "cleaner": {
-    // Kodu will NEVER remove comments starting with these:
-    "whitelist": ["//!"]
+    "whitelist": ["//!"],
+    "keepJSDoc": true,
+    "useGitignore": true
   },
   "packer": {
-    "ignore": ["package-lock.json", "dist", "coverage"]
-  },
-  "ops": {
-    "servers": {
-      "dev": {
-        "host": "example.com",
-        "port": 22,
-        "user": "ubuntu",
-        "sshKeyPath": "~/.ssh/id_rsa",
-        "paths": {
-          "apps": "/var/agent-apps",
-          "caddy": "/var/agent-apps/caddy"
-        }
-      }
-    }
-  },
+    "ignore": ["package-lock.json", "dist", "coverage"],
+    "useGitignore": true
+  }
+}
+```
+
+Both commands work without a config file using sensible defaults.
+
+### Custom pack template
+
+Point `prompts.pack` at a markdown file to wrap packed context in a prompt:
+
+```json
+{
   "prompts": {
-    "review": {
-      "bug": ".kodu/prompts/review-bug.md"
-    }
+    "pack": ".kodu/prompts/pack.md"
   }
 }
 ```
 
-`kodu ops` is designed for agents: responses are strict JSON (including errors), with no spinner/colors/prompts.
-</details>
+Available template variables: `{{context}}`, `{{fileList}}`, `{{tokenCount}}`, `{{usdEstimate}}`.
 
 ---
 
-## 🏎️ Tech Stack (Fresh & Modern)
-
-Built for speed and maintainability.
+## Privacy
 
-*   **Runtime:** Node.js (ESM)
-*   **Framework:** NestJS + Commander
-*   **Parsing:** `ts-morph` (AST-based, not Regex)
-*   **Globbing:** `tinyglobby`
-*   **UI:** `@inquirer` + `yocto-spinner`
+- All processing runs locally
+- No data sent anywhere
+- API keys are never stored — only read from env vars
 
 ---
 
 <div align="center">
-  <sub>Built with ❤️ for productive developers.</sub>
+  <sub>Built for productive developers.</sub>
   <br>
   <a href="CONTRIBUTING.md">Contributing</a> • <a href="LICENSE">License</a>
 </div>

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "kodu",
-    "version": "1.2.0",
+    "version": "2.0.1",
     "description": "High-performance CLI to prepare codebase for LLMs, automate reviews, and draft commits.",
     "repository": {
         "type": "git",
@@ -50,7 +50,6 @@
         "@inquirer/confirm": "^6.0.4",
         "@inquirer/input": "^5.0.4",
         "@inquirer/select": "^5.0.4",
-        "@mastra/core": "^1.0.4",
         "@nestjs/common": "^11.0.1",
         "@nestjs/core": "^11.0.1",
         "clipboardy": "^5.0.2",

package/dist/src/app.module.js

@@ -9,15 +9,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppModule = void 0;
 const common_1 = require("@nestjs/common");
 const clean_module_1 = require("./commands/clean/clean.module");
-const commit_module_1 = require("./commands/commit/commit.module");
 const init_module_1 = require("./commands/init/init.module");
-const ops_module_1 = require("./commands/ops/ops.module");
 const pack_module_1 = require("./commands/pack/pack.module");
-const review_module_1 = require("./commands/review/review.module");
 const config_module_1 = require("./core/config/config.module");
 const fs_module_1 = require("./core/file-system/fs.module");
 const ui_module_1 = require("./core/ui/ui.module");
-const ai_module_1 = require("./shared/ai/ai.module");
 const git_module_1 = require("./shared/git/git.module");
 const tokenizer_module_1 = require("./shared/tokenizer/tokenizer.module");
 let AppModule = class AppModule {
@@ -30,14 +26,10 @@ exports.AppModule = AppModule = __decorate([
             ui_module_1.UiModule,
             fs_module_1.FsModule,
             git_module_1.GitModule,
-            ai_module_1.AiModule,
             tokenizer_module_1.TokenizerModule,
             init_module_1.InitModule,
             pack_module_1.PackModule,
             clean_module_1.CleanModule,
-            review_module_1.ReviewModule,
-            commit_module_1.CommitModule,
-            ops_module_1.OpsModule,
         ],
     })
 ], AppModule);

package/dist/src/app.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.module.js","sourceRoot":"","sources":["../../src/app.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAwC;AACxC,gEAA4D;AAC5D,mEAA+D;AAC/D,6DAAyD;AACzD,0DAAsD;AACtD,6DAAyD;AACzD,mEAA+D;AAC/D,+DAA2D;AAC3D,4DAAwD;AACxD,mDAA+C;AAC/C,qDAAiD;AACjD,wDAAoD;AACpD,0EAAsE;AAkB/D,IAAM,SAAS,GAAf,MAAM,SAAS;CAAG,CAAA;AAAZ,8BAAS;oBAAT,SAAS;IAhBrB,IAAA,eAAM,EAAC;QACN,OAAO,EAAE;YACP,4BAAY;YACZ,oBAAQ;YACR,oBAAQ;YACR,sBAAS;YACT,oBAAQ;YACR,kCAAe;YACf,wBAAU;YACV,wBAAU;YACV,0BAAW;YACX,4BAAY;YACZ,4BAAY;YACZ,sBAAS;SACV;KACF,CAAC;GACW,SAAS,CAAG"}
+{"version":3,"file":"app.module.js","sourceRoot":"","sources":["../../src/app.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAwC;AACxC,gEAA4D;AAC5D,6DAAyD;AACzD,6DAAyD;AACzD,+DAA2D;AAC3D,4DAAwD;AACxD,mDAA+C;AAC/C,wDAAoD;AACpD,0EAAsE;AAc/D,IAAM,SAAS,GAAf,MAAM,SAAS;CAAG,CAAA;AAAZ,8BAAS;oBAAT,SAAS;IAZrB,IAAA,eAAM,EAAC;QACN,OAAO,EAAE;YACP,4BAAY;YACZ,oBAAQ;YACR,oBAAQ;YACR,sBAAS;YACT,kCAAe;YACf,wBAAU;YACV,wBAAU;YACV,0BAAW;SACZ;KACF,CAAC;GACW,SAAS,CAAG"}

package/dist/src/commands/clean/clean.command.d.ts

@@ -7,6 +7,11 @@ import { GitService } from '../../shared/git/git.service';
 type CleanOptions = {
     dryRun?: boolean;
     changed?: boolean;
+    staged?: boolean;
+    backup?: boolean;
+    noJsdoc?: boolean;
+    verbose?: boolean;
+    stdin?: boolean;
 };
 export declare class CleanCommand extends CommandRunner {
     private readonly ui;
@@ -17,8 +22,16 @@ export declare class CleanCommand extends CommandRunner {
     constructor(ui: UiService, fsService: FsService, cleaner: CleanerService, config: ConfigService, git: GitService);
     parseDryRun(): boolean;
     parseChanged(): boolean;
-    run(_inputs: string[], options?: CleanOptions): Promise<void>;
+    parseStaged(): boolean;
+    parseBackup(): boolean;
+    parseNoJsdoc(): boolean;
+    parseVerbose(): boolean;
+    parseStdin(): boolean;
+    run(inputs: string[], options?: CleanOptions): Promise<void>;
+    private runStdin;
+    private readStdin;
     private buildSpinnerText;
+    private noFilesMessage;
     private collectTargets;
 }
 export {};