kodu 2.1.3 → 3.0.1

package/README.md

@@ -23,14 +23,32 @@
 
 ## Install
 
+Kodu is a single native binary (written in Go). Pick any channel:
+
 ```bash
+# npm (downloads the prebuilt binary for your platform on install)
 npm install -g kodu
+
+# Go toolchain
+go install github.com/uxname/kodu/cmd/kodu@latest
+
+# Prebuilt binaries (linux/macOS/windows × amd64/arm64)
+# https://github.com/uxname/kodu/releases
 ```
 
-Or run without installing:
+> The npm package ships a thin launcher whose `postinstall` fetches the matching
+> binary from GitHub Releases. If the download fails (offline, proxy), it prints
+> a hint to use `go install` instead — `npm install` itself never breaks.
+
+### Build from source
+
+Requires Go 1.25+ and a C toolchain (CGO is used for the tree-sitter parsers).
 
 ```bash
-npx kodu pack --copy
+git clone https://github.com/uxname/kodu.git && cd kodu
+make build      # → dist/kodu
+make test       # run the test suite
+make lint       # gofmt + go vet + golangci-lint
 ```
 
 ---
@@ -101,7 +119,10 @@ src/core/config/config.service.ts  ← import from src/core/config/config.module
 src/shared/constants.ts  ← import from src/core/file-system/fs.service.ts
 ```
 
-`--deps` uses `ts-morph` to resolve the TypeScript import graph, so it correctly handles tsconfig path aliases, re-exports, index files, and type-only imports. `node_modules` are excluded automatically.
+`--deps` resolves the TypeScript/JavaScript import graph (relative imports, file
+extensions, index files, `tsconfig` path aliases, re-exports, and type-only
+imports), excluding `node_modules`. Resolution is best-effort and does not cover
+exotic cases like package.json `exports` maps.
 
 ### Output format
 

package/bin/kodu.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Thin launcher: runs the native kodu binary downloaded by postinstall.
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+
+const binName = process.platform === 'win32' ? 'kodu.exe' : 'kodu';
+const binPath = path.join(__dirname, binName);
+
+if (!fs.existsSync(binPath)) {
+  console.error('[kodu] Native binary not found. Reinstall the package or build it from source:');
+  console.error('[kodu]   go install github.com/uxname/kodu/cmd/kodu@latest');
+  process.exit(1);
+}
+
+const res = spawnSync(binPath, process.argv.slice(2), { stdio: 'inherit' });
+if (res.error) {
+  console.error(`[kodu] ${res.error.message}`);
+  process.exit(1);
+}
+process.exit(res.status ?? 0);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kodu",
-  "version": "2.1.3",
-  "description": "High-performance CLI to prepare codebase for LLMs, automate reviews, and draft commits.",
+  "version": "3.0.1",
+  "description": "High-performance CLI to prepare a codebase for LLMs, automate reviews, and draft commits. Native Go binary.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/uxname/kodu.git"
@@ -16,81 +16,25 @@
     "llm",
     "developer-tools",
     "productivity",
-    "typescript",
+    "golang",
     "openai",
     "automation",
     "code-review",
     "context-window",
     "git-tools"
   ],
-  "private": false,
   "license": "MIT",
   "bin": {
-    "kodu": "dist/src/main.js"
+    "kodu": "bin/kodu.js"
   },
+  "files": [
+    "bin/kodu.js",
+    "scripts/postinstall.js"
+  ],
   "scripts": {
-    "________________ BUILD AND RUN ________________": "",
-    "build": "nest build && chmod +x dist/src/main.js",
-    "generate:schema": "ts-node scripts/generate-json-schema.ts",
-    "postbuild": "npm run generate:schema",
-    "start:prod": "node dist/main.js",
-    "start:dev": "nest start --watch",
-    "new:command": "nest g -c nest-commander-schematics command",
-    "new:question": "nest g -c nest-commander-schematics question",
-    "________________ FORMAT AND LINT ________________": "",
-    "lint": "biome check",
-    "lint:fix": "biome check --write",
-    "lint:fix:unsafe": "biome check --write --unsafe",
-    "ts:check": "tsc --noEmit",
-    "knip": "knip --production",
-    "check": "run-p ts:check lint:fix knip",
-    "________________ TEST ________________": "",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:cov": "vitest run --coverage",
-    "________________ OTHER ________________": "",
-    "prepare": "is-ci || lefthook install",
-    "update": "npx npm-check-updates -u && rimraf node_modules package-lock.json && npm i",
-    "postupdate": "npm run lint:fix && npm run check"
-  },
-  "dependencies": {
-    "@inquirer/confirm": "^6.0.4",
-    "@inquirer/input": "^5.0.4",
-    "@inquirer/select": "^5.0.4",
-    "@nestjs/common": "^11.0.1",
-    "@nestjs/core": "^11.0.1",
-    "clipboardy": "^5.0.2",
-    "execa": "^9.6.1",
-    "ignore": "^7.0.5",
-    "js-tiktoken": "^1.0.21",
-    "lilconfig": "^3.1.3",
-    "nest-commander": "^3.20.1",
-    "picocolors": "^1.1.1",
-    "reflect-metadata": "^0.2.2",
-    "rxjs": "^7.8.1",
-    "source-map-support": "^0.5.21",
-    "tinyglobby": "^0.2.15",
-    "ts-morph": "^24.0.0",
-    "yocto-spinner": "^1.0.0",
-    "zod": "^4.3.6"
+    "postinstall": "node scripts/postinstall.js"
   },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.12",
-    "@nestjs/cli": "^11.0.0",
-    "@nestjs/schematics": "^11.0.0",
-    "@nestjs/testing": "^11.0.1",
-    "@types/node": "^22.10.7",
-    "is-ci": "^4.1.0",
-    "knip": "^5.82.1",
-    "lefthook": "^2.0.15",
-    "nest-commander-schematics": "^3.2.0",
-    "npm-check-updates": "^18.3.1",
-    "npm-run-all": "^4.1.5",
-    "rimraf": "^6.1.3",
-    "ts-loader": "^9.5.2",
-    "ts-node": "^10.9.2",
-    "tsconfig-paths": "^4.2.0",
-    "typescript": "^5.7.3",
-    "vitest": "^3.2.4"
+  "engines": {
+    "node": ">=18"
   }
 }

package/scripts/postinstall.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Downloads the native kodu binary for the current platform from GitHub Releases.
+// On failure it does not break the install — it prints a hint (graceful degradation).
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const https = require('node:https');
+const { execFileSync } = require('node:child_process');
+
+const REPO = 'uxname/kodu';
+const pkg = require('../package.json');
+
+const PLATFORMS = { linux: 'linux', darwin: 'darwin', win32: 'windows' };
+const ARCHES = { x64: 'amd64', arm64: 'arm64' };
+
+function fail(msg) {
+  console.warn(`\n[kodu] ${msg}`);
+  console.warn('[kodu] Install manually: go install github.com/uxname/kodu/cmd/kodu@latest');
+  console.warn(`[kodu] or download the binary: https://github.com/${REPO}/releases\n`);
+  process.exit(0); // do not block npm install
+}
+
+const goos = PLATFORMS[process.platform];
+const goarch = ARCHES[process.arch];
+if (!goos || !goarch) fail(`Platform ${process.platform}/${process.arch} is not supported by a prebuilt binary.`);
+
+const ext = goos === 'windows' ? 'zip' : 'tar.gz';
+const binName = goos === 'windows' ? 'kodu.exe' : 'kodu';
+const asset = `kodu_v${pkg.version}_${goos}_${goarch}.${ext}`;
+const url = `https://github.com/${REPO}/releases/download/v${pkg.version}/${asset}`;
+const binDir = path.join(__dirname, '..', 'bin');
+
+function download(u, dest, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirects > 5) return reject(new Error('too many redirects'));
+    https.get(u, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        return resolve(download(res.headers.location, dest, redirects + 1));
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode} for ${u}`));
+      }
+      const file = fs.createWriteStream(dest);
+      res.pipe(file);
+      file.on('finish', () => file.close(resolve));
+      file.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+(async () => {
+  try {
+    fs.mkdirSync(binDir, { recursive: true });
+    const archivePath = path.join(binDir, asset);
+    await download(url, archivePath);
+    // bsdtar (tar) extracts both .tar.gz and .zip on Linux/macOS/Win10+.
+    execFileSync('tar', ['-xf', archivePath, '-C', binDir], { stdio: 'ignore' });
+    fs.rmSync(archivePath, { force: true });
+    const binPath = path.join(binDir, binName);
+    if (!fs.existsSync(binPath)) throw new Error('binary not found after extraction');
+    if (goos !== 'windows') fs.chmodSync(binPath, 0o755);
+    console.log(`[kodu] Installed binary ${goos}/${goarch} v${pkg.version}`);
+  } catch (err) {
+    fail(`Failed to download the binary: ${err.message}`);
+  }
+})();

package/AGENTS.md

@@ -1,214 +0,0 @@
-# AGENTS.md
-
-This file provides guidelines and instructions for AI assistants working on the Kodu project.
-
-## 1. Project Overview
-
-**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)
-- **Available Commands:** `pack`, `clean`
-
-## 2. Technology Stack (Enforced)
-
-| Category | USE | DO NOT USE |
-|----------|-----|------------|
-| Framework | NestJS + nest-commander | Pure Node.js, Oclif |
-| File System | node:fs/promises + tinyglobby | fs-extra, glob, rimraf |
-| Config | lilconfig | cosmiconfig, rc |
-| Validation | zod | class-validator, joi |
-| CLI UI | @inquirer/prompts + picocolors | inquirer (legacy), chalk |
-| Spinners | yocto-spinner | ora, cli-spinners |
-| AST/Parsing | ts-morph | Regex, babel |
-| Tokens | js-tiktoken | gpt-3-encoder |
-| Clipboard | clipboardy | Native APIs |
-
-## 3. Architecture
-
-```
-src/
-├── app.module.ts           # Root Orchestrator
-├── main.ts                 # Entry Point
-├── core/                   # Global Infrastructure
-│   ├── config/             # ConfigModule (Zod + lilconfig)
-│   ├── file-system/        # FsModule (tinyglobby)
-│   └── ui/                 # UiModule (spinners, loggers)
-├── shared/                 # Shared Business Logic
-│   ├── tokenizer/          # TokenizerModule
-│   ├── git/                # GitModule
-│   └── cleaner/            # CleanerService (AST)
-└── commands/               # Feature Commands
-    ├── pack/               # kodu pack
-    └── clean/              # kodu clean
-```
-
-## 4. Build, Lint & Test Commands
-
-### Essential Commands
-```bash
-# Build the project
-npm run build              # Full build (Nest build) + make executable
-
-# Run the built artifact
-npm run start:prod         # Run from dist/
-
-# Type check
-npm run ts:check           # TypeScript compilation check
-
-# Lint and format
-npm run lint               # Run Biome linter
-npm run lint:fix           # Biome with auto-fix
-
-# Full check (required before commit)
-npm run check              # TypeCheck + Biome + Knip
-```
-
-## 5. Code Style Guidelines
-
-### General
-- **ESM Only:** Use `import` statements (nodenext mode)
-- **Strict Mode:** `strictNullChecks` is ON. Avoid `any`; use `unknown` with narrowing
-- **Quotes:** Single quotes preferred
-- **Indentation:** 2 spaces
-- **No Comments:** Unless explicitly requested by user
-
-### Imports
-- Use explicit relative imports: `import { Foo } from './foo'`
-- Avoid barrel exports (`index.ts`) unless necessary
-- No circular dependencies (NestJS module structure enforces this)
-
-### Types
-- Prefer explicit types over `any`
-- Use `unknown` and narrow with type guards or Zod validation
-- Interface over type for object shapes
-- Use readonly for immutable data
-
-### Naming Conventions
-- **Files:** kebab-case (`my-file.ts`)
-- **Classes:** PascalCase (`MyClass`)
-- **Functions:** camelCase (`myFunction`)
-- **Constants:** UPPER_SNAKE_CASE for compile-time constants
-- **Interfaces:** PascalCase, no `I` prefix (`User` not `IUser`)
-
-### Error Handling
-- Use custom error classes extending `Error`
-- Never swallow errors silently
-- Provide meaningful error messages
-- Use try/catch with specific error types
-- Validate inputs with Zod schemas
-
-### NestJS Specifics
-- All commands extend `CommandRunner` from `nest-commander`
-- Use Dependency Injection - never import services directly
-- Register modules in `app.module.ts`
-- Use `@Injectable()` decorator for services
-
-## 6. Configuration (kodu.json)
-
-```json
-{
-  "cleaner": {
-    "whitelist": ["//!"],
-    "keepJSDoc": true,
-    "useGitignore": true
-  },
-  "packer": {
-    "ignore": ["*.lock", "node_modules", "dist"],
-    "useGitignore": true
-  }
-}
-```
-
-- Config validated via Zod on startup
-- `kodu.json` must be in current working directory
-
-## 7. Commands Reference
-
-### `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:** Both commands are deterministic — no AI integration
-2. **Validation First:** Invalid `kodu.json` causes graceful crash with Zod error
-3. **Performance:** Mindful of import costs. Use lightweight libraries
-4. **Config Location:** `kodu.json` must be in current working directory
-
-## 9. Development Workflow
-
-### Adding a New Command
-1. Create `src/commands/<name>/`
-2. Create `<name>.command.ts` and `<name>.module.ts`
-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/src/main.js <name>`
-
-### Before Commit
-Always run:
-```bash
-npm run check
-```
-
-This executes: TypeScript check + Biome lint + Knip dead code detection.
-
-## 10. Testing Strategy
-
-- **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
-
-## 11. Release Process
-
-### Prerequisites
-- Working directory must be clean (`git status` — no dirty files)
-- All changes committed and pushed
-- You have npm publish access
-
-### Steps
-```bash
-# 1. Ensure clean working directory
-git status
-
-# 2. Bump version, build, publish
-npm version patch && npm run build && npm publish --access public
-
-# 3. Push the version bump commit and tag
-git push && git push --tags
-```
-
-- Use `npm version minor` for new features, `npm version major` for breaking changes
-- The `npm version` command creates a git tag automatically (e.g. `v2.1.3`)
-
-## 12. Handling Uncertainties
-
-- Unclear requirements? Ask the user first
-- Library not in Tech Stack section? Prefer native Node.js APIs
-- New dependency? Ensure it follows "Fresh & Modern" strategy
-- Breaking changes? Create an OpenSpec proposal

package/__tests__/core/fs/fs.service.test.ts

@@ -1,72 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { ConfigService } from '../../../src/core/config/config.service';
-import { FsService } from '../../../src/core/file-system/fs.service';
-import { UiService } from '../../../src/core/ui/ui.service';
-
-vi.mock('../../../src/core/config/config.service', () => ({
-  ConfigService: vi.fn().mockImplementation(() => ({
-    getConfig: () => ({
-      cleaner: { whitelist: [], keepJSDoc: false },
-      packer: { ignore: ['node_modules', 'dist'], useGitignore: false },
-    }),
-  })),
-}));
-
-vi.mock('../../../src/core/ui/ui.service', () => ({
-  UiService: vi.fn().mockImplementation(() => ({
-    log: { warn: vi.fn() },
-  })),
-}));
-
-describe('FsService', () => {
-  let fsService: FsService;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    const configService = new ConfigService() as never;
-    const uiService = new UiService() as never;
-    fsService = new FsService(configService, uiService);
-  });
-
-  describe('findProjectFiles', () => {
-    it('should find ts files in current directory', async () => {
-      const files = await fsService.findProjectFiles({
-        ignore: ['node_modules', 'dist'],
-        useGitignore: false,
-      });
-
-      const tsFiles = files.filter((f) => f.endsWith('.ts'));
-      expect(tsFiles.length).toBeGreaterThan(0);
-    });
-
-    it('should exclude node_modules by default', async () => {
-      const files = await fsService.findProjectFiles({
-        ignore: ['node_modules', 'dist'],
-        useGitignore: false,
-      });
-
-      const hasNodeModules = files.some((f) => f.includes('node_modules'));
-      expect(hasNodeModules).toBe(false);
-    });
-
-    it('should return relative paths', async () => {
-      const files = await fsService.findProjectFiles({
-        ignore: [],
-        useGitignore: false,
-      });
-
-      const hasAbsolute = files.some((f) => f.startsWith('/'));
-      expect(hasAbsolute).toBe(false);
-    });
-
-    it('should return sorted paths', async () => {
-      const files = await fsService.findProjectFiles({
-        ignore: [],
-        useGitignore: false,
-      });
-
-      const sorted = [...files].sort((a, b) => a.localeCompare(b));
-      expect(files).toEqual(sorted);
-    });
-  });
-});

package/__tests__/shared/cleaner/cleaner.service.test.ts

@@ -1,102 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { ConfigService } from '../../../src/core/config/config.service';
-
-vi.mock('../../../src/core/config/config.service', () => ({
-  ConfigService: vi.fn().mockImplementation(() => ({
-    getConfig: () => ({
-      cleaner: {
-        whitelist: [],
-        keepJSDoc: false,
-        useGitignore: false,
-      },
-      packer: {
-        ignore: [],
-        useGitignore: false,
-      },
-    }),
-  })),
-}));
-
-vi.mock('../../../src/core/file-system/fs.service', () => ({
-  FsService: vi.fn().mockImplementation(() => ({})),
-}));
-
-describe('CleanerService', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('should remove single-line comments', async () => {
-    const { CleanerService } = await import(
-      '../../../src/shared/cleaner/cleaner.service'
-    );
-    const configService = new ConfigService() as never;
-    const fsService = {} as never;
-    const cleaner = new CleanerService(configService, fsService);
-
-    const input = `const x = 1; // comment
-const y = 2;`;
-    const result = cleaner.cleanContent('test.ts', input);
-
-    expect(result).toBe('const x = 1; \nconst y = 2;');
-  });
-
-  it('should remove multi-line comments', async () => {
-    const { CleanerService } = await import(
-      '../../../src/shared/cleaner/cleaner.service'
-    );
-    const configService = new ConfigService() as never;
-    const fsService = {} as never;
-    const cleaner = new CleanerService(configService, fsService);
-
-    const input = `/* comment */
-const x = 1;`;
-    const result = cleaner.cleanContent('test.ts', input);
-
-    expect(result).toBe('\nconst x = 1;');
-  });
-
-  it('should preserve comments in whitelist', async () => {
-    const { CleanerService } = await import(
-      '../../../src/shared/cleaner/cleaner.service'
-    );
-    const configService = new ConfigService() as never;
-    const fsService = {} as never;
-    const cleaner = new CleanerService(configService, fsService);
-
-    const input = `const x = 1; // eslint-disable-line
-const y = 2;`;
-    const result = cleaner.cleanContent('test.ts', input);
-
-    expect(result).toBe('const x = 1; // eslint-disable-line\nconst y = 2;');
-  });
-
-  it('should keep JSDoc when option is set', async () => {
-    const { CleanerService } = await import(
-      '../../../src/shared/cleaner/cleaner.service'
-    );
-    const configService = new ConfigService() as never;
-    const fsService = {} as never;
-    const cleaner = new CleanerService(configService, fsService);
-
-    const input = `/** JSDoc */
-const x = 1;`;
-    const result = cleaner.cleanContent('test.ts', input, true);
-
-    expect(result).toBe('/** JSDoc */\nconst x = 1;');
-  });
-
-  it('should remove JSX expression without content', async () => {
-    const { CleanerService } = await import(
-      '../../../src/shared/cleaner/cleaner.service'
-    );
-    const configService = new ConfigService() as never;
-    const fsService = {} as never;
-    const cleaner = new CleanerService(configService, fsService);
-
-    const input = `const x = <>{/* comment */}</>;`;
-    const result = cleaner.cleanContent('test.tsx', input);
-
-    expect(result).toBe('const x = <></>;');
-  });
-});