kodu 1.1.14 → 1.1.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/AGENTS.md +184 -199
  2. package/README.md +32 -3
  3. package/dist/package.json +86 -0
  4. package/dist/src/app.module.js +2 -0
  5. package/dist/src/app.module.js.map +1 -1
  6. package/dist/src/commands/init/init.command.js +16 -0
  7. package/dist/src/commands/init/init.command.js.map +1 -1
  8. package/dist/src/commands/ops/ops.command.d.ts +4 -0
  9. package/dist/src/commands/ops/ops.command.js +39 -0
  10. package/dist/src/commands/ops/ops.command.js.map +1 -0
  11. package/dist/src/commands/ops/ops.module.d.ts +2 -0
  12. package/dist/src/commands/ops/ops.module.js +33 -0
  13. package/dist/src/commands/ops/ops.module.js.map +1 -0
  14. package/dist/src/commands/ops/ops.types.d.ts +13 -0
  15. package/dist/src/commands/ops/ops.types.js +12 -0
  16. package/dist/src/commands/ops/ops.types.js.map +1 -0
  17. package/dist/src/commands/ops/ops.utils.d.ts +13 -0
  18. package/dist/src/commands/ops/ops.utils.js +117 -0
  19. package/dist/src/commands/ops/ops.utils.js.map +1 -0
  20. package/dist/src/commands/ops/subcommands/ops-env.command.d.ts +17 -0
  21. package/dist/src/commands/ops/subcommands/ops-env.command.js +109 -0
  22. package/dist/src/commands/ops/subcommands/ops-env.command.js.map +1 -0
  23. package/dist/src/commands/ops/subcommands/ops-routes.command.d.ts +18 -0
  24. package/dist/src/commands/ops/subcommands/ops-routes.command.js +166 -0
  25. package/dist/src/commands/ops/subcommands/ops-routes.command.js.map +1 -0
  26. package/dist/src/commands/ops/subcommands/ops-service.command.d.ts +16 -0
  27. package/dist/src/commands/ops/subcommands/ops-service.command.js +128 -0
  28. package/dist/src/commands/ops/subcommands/ops-service.command.js.map +1 -0
  29. package/dist/src/commands/ops/subcommands/ops-sysinfo.command.d.ts +9 -0
  30. package/dist/src/commands/ops/subcommands/ops-sysinfo.command.js +60 -0
  31. package/dist/src/commands/ops/subcommands/ops-sysinfo.command.js.map +1 -0
  32. package/dist/src/core/config/config.schema.d.ts +28 -0
  33. package/dist/src/core/config/config.schema.js +19 -0
  34. package/dist/src/core/config/config.schema.js.map +1 -1
  35. package/dist/src/main.js +7 -1
  36. package/dist/src/main.js.map +1 -1
  37. package/dist/src/shared/ssh/ssh.module.d.ts +2 -0
  38. package/dist/src/shared/ssh/ssh.module.js +21 -0
  39. package/dist/src/shared/ssh/ssh.module.js.map +1 -0
  40. package/dist/src/shared/ssh/ssh.service.d.ts +11 -0
  41. package/dist/src/shared/ssh/ssh.service.js +53 -0
  42. package/dist/src/shared/ssh/ssh.service.js.map +1 -0
  43. package/dist/tsconfig.build.tsbuildinfo +1 -1
  44. package/docs/plans/2026-03-01-agentops-design.md +194 -0
  45. package/docs/plans/2026-03-01-agentops-implementation.md +358 -0
  46. package/kodu.json +15 -0
  47. package/kodu.schema.json +59 -0
  48. package/package.json +1 -1
  49. package/src/app.module.ts +2 -0
  50. package/src/commands/init/init.command.ts +16 -0
  51. package/src/commands/ops/ops.command.ts +30 -0
  52. package/src/commands/ops/ops.module.ts +20 -0
  53. package/src/commands/ops/ops.types.ts +24 -0
  54. package/src/commands/ops/ops.utils.ts +156 -0
  55. package/src/commands/ops/subcommands/ops-env.command.ts +121 -0
  56. package/src/commands/ops/subcommands/ops-routes.command.ts +185 -0
  57. package/src/commands/ops/subcommands/ops-service.command.ts +154 -0
  58. package/src/commands/ops/subcommands/ops-sysinfo.command.ts +53 -0
  59. package/src/core/config/config.schema.ts +23 -0
  60. package/src/main.ts +4 -1
  61. package/src/shared/ssh/ssh.module.ts +8 -0
  62. package/src/shared/ssh/ssh.service.ts +61 -0
  63. package/.cursor/commands/openspec-apply.md +0 -23
  64. package/.cursor/commands/openspec-archive.md +0 -27
  65. package/.cursor/commands/openspec-proposal.md +0 -28
  66. package/.windsurf/workflows/openspec-apply.md +0 -21
  67. package/.windsurf/workflows/openspec-archive.md +0 -25
  68. package/.windsurf/workflows/openspec-proposal.md +0 -26
  69. package/openspec/AGENTS.md +0 -456
  70. package/openspec/changes/archive/2026-01-26-translate-project-to-english/design.md +0 -30
  71. package/openspec/changes/archive/2026-01-26-translate-project-to-english/proposal.md +0 -17
  72. package/openspec/changes/archive/2026-01-26-translate-project-to-english/specs/ai/spec.md +0 -26
  73. package/openspec/changes/archive/2026-01-26-translate-project-to-english/specs/cleaner/spec.md +0 -26
  74. package/openspec/changes/archive/2026-01-26-translate-project-to-english/specs/config/spec.md +0 -22
  75. package/openspec/changes/archive/2026-01-26-translate-project-to-english/specs/ui/spec.md +0 -33
  76. package/openspec/changes/archive/2026-01-26-translate-project-to-english/tasks.md +0 -33
  77. package/openspec/project.md +0 -72
  78. package/openspec/specs/cleaner/spec.md +0 -31
package/AGENTS.md CHANGED
@@ -1,119 +1,139 @@
1
- <!-- OPENSPEC:START -->
2
- # OpenSpec Instructions
1
+ # AGENTS.md
3
2
 
4
- These instructions are for AI assistants working in this project.
3
+ This file provides guidelines and instructions for AI assistants working on the Kodu project.
5
4
 
6
- Always open `@/openspec/AGENTS.md` when the request:
7
- - Mentions planning or proposals (words like proposal, spec, change, plan)
8
- - Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
9
- - Sounds ambiguous and you need the authoritative spec before coding
5
+ ## 1. Project Overview
10
6
 
11
- Use `@/openspec/AGENTS.md` to learn:
12
- - How to create and apply change proposals
13
- - Spec format and conventions
14
- - Project structure and guidelines
7
+ **Kodu** is a high-performance CLI utility that bridges local development environments with LLMs. It automates context preparation, code cleaning, reviews, and commit drafting.
15
8
 
16
- Keep this managed block so 'openspec update' can refresh the instructions.
9
+ - **Key Goals:** Speed (<0.5s startup), Determinism (no AI for critical file ops), DX (Developer Experience)
10
+ - **Current Phase:** Phase 4 - AI Integration with Mastra/Git
11
+ - **Available Commands:** `init`, `pack`, `clean`, `review`, `commit`, `ops`
17
12
 
18
- <!-- OPENSPEC:END -->
19
-
20
- # AGENTS
13
+ ## 2. Technology Stack (Enforced)
21
14
 
22
- ## 1. Project Overview & Philosophy
23
- - **Kodu** is a CLI assistant for developers (JS/TS focus) to streamline interactions with LLMs.
24
- - **Key Goals:** Speed (0.5s startup), Determinism (no AI for critical file ops), and DX (Developer Experience).
25
- - **Source of Truth:**
26
- - Functional scope: `docs/project_charter.md`.
27
- - Roadmap & Tech Stack: `docs/plan.md`.
28
- - **Current Phase:** **Phase 4: AI Integration** — Mastra/Git integration, `review` and `commit` commands, diff filtering via `packer.ignore`.
29
- - **Available Commands:** `init`, `pack`, `clean`, `review`, `commit` (all registered in `app.module.ts`).
15
+ | Category | USE | DO NOT USE |
16
+ |----------|-----|------------|
17
+ | Framework | NestJS + nest-commander | Pure Node.js, Oclif |
18
+ | File System | node:fs/promises + tinyglobby | fs-extra, glob, rimraf |
19
+ | Config | lilconfig | cosmiconfig, rc |
20
+ | Validation | zod | class-validator, joi |
21
+ | Process/Git | execa | child_process, shelljs |
22
+ | CLI UI | @inquirer/prompts + picocolors | inquirer (legacy), chalk |
23
+ | Spinners | yocto-spinner | ora, cli-spinners |
24
+ | AI Agent | mastra | Direct openai SDK |
25
+ | AST/Parsing | ts-morph | Regex, babel |
26
+ | Tokens | js-tiktoken | gpt-3-encoder |
27
+ | Clipboard | clipboardy | Native APIs |
28
+
29
+ ## 3. Architecture
30
30
 
31
- ## 2. Technology Stack (Enforced)
32
- We strictly follow the "Fresh & Modern" stack strategy. Do not install legacy libraries.
33
-
34
- | Category | **USE THIS** ✅ | **DO NOT USE** ❌ |
35
- | :--- | :--- | :--- |
36
- | **Framework** | `NestJS` + `nest-commander` | Pure Node.js scripts, Oclif |
37
- | **File System** | `node:fs/promises` + `tinyglobby` | `fs-extra`, `glob`, `fast-glob`, `rimraf` |
38
- | **Config Loading** | `lilconfig` | `cosmiconfig`, `rc` |
39
- | **Validation** | `zod` | `class-validator`, `joi` |
40
- | **Process/Git** | `execa` | `child_process`, `shelljs` |
41
- | **CLI UI** | `@inquirer/prompts` + `picocolors` | `inquirer` (legacy), `chalk`, `colors` |
42
- | **Spinners** | `yocto-spinner` | `ora`, `cli-spinners` |
43
- | **AI Agent** | `mastra` | Direct `openai` SDK calls (unless inside Mastra) |
44
- | **AST/Parsing** | `ts-morph` | Regex for code parsing, `babel` |
45
- | **Tokens** | `js-tiktoken` | `gpt-3-encoder` |
46
- | **Git** | `git` via `execa` | `child_process`, `shelljs` |
47
- | **Clipboard** | `clipboardy` | Native clipboard APIs |
48
-
49
- ## 3. Architecture & Module Map
50
- The project is NOT a flat structure. Use the following Module Map as a guide for where to place files.
51
-
52
- ```text
31
+ ```
53
32
  src/
54
- ├── app.module.ts # Root Orchestrator
55
- ├── main.ts # Entry Point
56
-
57
- ├── core/ # GLOBAL Infrastructure (Global Modules)
58
- │ ├── config/ # ConfigModule (Zod schemas, lilconfig for kodu.json)
59
- ├── file-system/ # FsModule (tinyglobby wrappers)
60
- │ └── ui/ # UiModule (Spinners, colored loggers)
61
-
62
- ├── shared/ # Shared Business Logic
63
- │ ├── tokenizer/ # TokenizerModule (js-tiktoken)
64
- ├── git/ # GitModule (execa git helpers, diff filters)
65
- ├── ai/ # AiModule (Mastra agents, API key from llm.apiKeyEnv)
66
- └── cleaner/ # CleanerService (AST-based comment removal, used by CleanModule)
67
-
68
- └── commands/ # Feature Modules (The actual commands)
69
- ├── init/ # InitModule (kodu init)
70
- ├── pack/ # PackModule (kodu pack)
71
- ├── clean/ # CleanModule (kodu clean)
72
- ├── review/ # ReviewModule (kodu review)
73
- └── commit/ # CommitModule (kodu commit)
33
+ ├── app.module.ts # Root Orchestrator
34
+ ├── main.ts # Entry Point
35
+ ├── core/ # Global Infrastructure
36
+ ├── config/ # ConfigModule (Zod + lilconfig)
37
+ │ ├── file-system/ # FsModule (tinyglobby)
38
+ └── ui/ # UiModule (spinners, loggers)
39
+ ├── shared/ # Shared Business Logic
40
+ ├── tokenizer/ # TokenizerModule
41
+ ├── git/ # GitModule
42
+ │ ├── ai/ # AiModule (Mastra)
43
+ └── cleaner/ # CleanerService (AST)
44
+ └── ssh/ # SshModule (remote ops via SSH)
45
+ └── commands/ # Feature Commands
46
+ ├── init/ # kodu init
47
+ ├── pack/ # kodu pack
48
+ ├── clean/ # kodu clean
49
+ ├── review/ # kodu review
50
+ ├── commit/ # kodu commit
51
+ └── ops/ # kodu ops <subcommand>
74
52
  ```
75
53
 
76
- **Note:** `CleanerService` is a shared service (not a module) used by `CleanModule`. It's located in `shared/cleaner/` for code reuse.
54
+ ## 4. Build, Lint & Test Commands
77
55
 
78
- ## 4. Coding Standards & Conventions
56
+ ### Essential Commands
57
+ ```bash
58
+ # Build the project
59
+ npm run build # Full build (Nest build) + make executable
79
60
 
80
- ### 4.1. General
81
- - **ESM Only:** The project runs in `nodenext` mode. Use `import` statements.
82
- - **Strictness:** `strictNullChecks` is ON. No `any` allowed unless absolutely necessary (use `unknown` and refine).
83
- - **Async/Await:** Prefer `node:fs/promises` over sync methods where possible, but for CLI startup (Config loading), sync operations are acceptable if they improve perceived performance.
61
+ # Run the built artifact
62
+ npm run start:prod # Run from dist/
84
63
 
85
- ### 4.2. NestJS Specifics
86
- - **Dependency Injection:** Always use DI. Do not import services directly into other services without providing them in the Module.
87
- - **CommandRunner:** All commands extend `CommandRunner` from `nest-commander`.
88
- - **Zod Config:** Configuration is loaded ONCE in `ConfigModule` and validated. Other modules inject `ConfigService` to access typed settings.
89
- - **Module Registration:** All command modules must be imported in `src/app.module.ts`.
64
+ # Type check
65
+ npm run ts:check # TypeScript compilation check
66
+
67
+ # Lint and format
68
+ npm run lint # Run Biome linter
69
+ npm run lint:fix # Biome with auto-fix
70
+
71
+ # Full check (required before commit)
72
+ npm run check # TypeCheck + Biome + Knip
73
+
74
+ # Run tests (if configured)
75
+ npm test # Run all tests
76
+ npm test -- <pattern> # Run tests matching pattern
77
+ npm test -- --testPathPattern=<pattern> # Alternative
78
+ ```
90
79
 
91
- ### 4.3. Code Style (Biome)
92
- - We use **Biome** for linting and formatting.
93
- - **Quotes:** Single quotes.
94
- - **Indent:** 2 spaces.
95
- - **Run Check:** Always run `npm run lint` before finishing a task.
80
+ ### Running a Single Test
81
+ ```bash
82
+ # By file name
83
+ npm test -- filename
96
84
 
97
- ## 5. Development Workflow
85
+ # By pattern
86
+ npm test -- --testNamePattern="test name"
98
87
 
99
- ### 5.1. Adding a New Command
100
- 1. Create a folder in `src/commands/<name>`.
101
- 2. Create `<name>.command.ts` and `<name>.module.ts`.
102
- 3. Implement `run()` method extending `CommandRunner`.
103
- 4. Decorate the class with `@Command()` from `nest-commander`.
104
- 5. Register the module in `src/app.module.ts`.
105
- 6. **Test:** Run `npm run build && node dist/main.js <name>` to verify.
88
+ # Watch mode
89
+ npm test -- --watch
106
90
 
107
- ### 5.2. Scripts
108
- - `npm run build`: Full build (Nest build) + make executable.
109
- - `npm run start:prod`: Run the built artifact.
110
- - `npm run check`: Run TypeCheck + Biome + Knip (Dead code detection).
111
- - `npm run lint`: Run Biome linter.
112
- - `npm run lint:fix`: Run Biome with auto-fix.
91
+ # With coverage
92
+ npm test -- --coverage
93
+ ```
113
94
 
114
- ## 6. Configuration (`kodu.json`)
95
+ ## 5. Code Style Guidelines
96
+
97
+ ### General
98
+ - **ESM Only:** Use `import` statements (nodenext mode)
99
+ - **Strict Mode:** `strictNullChecks` is ON. Avoid `any`; use `unknown` with narrowing
100
+ - **Quotes:** Single quotes preferred
101
+ - **Indentation:** 2 spaces
102
+ - **No Comments:** Unless explicitly requested by user
103
+
104
+ ### Imports
105
+ - Use explicit relative imports: `import { Foo } from './foo'`
106
+ - Avoid barrel exports (`index.ts`) unless necessary
107
+ - No circular dependencies (NestJS module structure enforces this)
108
+
109
+ ### Types
110
+ - Prefer explicit types over `any`
111
+ - Use `unknown` and narrow with type guards or Zod validation
112
+ - Interface over type for object shapes
113
+ - Use readonly for immutable data
114
+
115
+ ### Naming Conventions
116
+ - **Files:** kebab-case (`my-file.ts`)
117
+ - **Classes:** PascalCase (`MyClass`)
118
+ - **Functions:** camelCase (`myFunction`)
119
+ - **Constants:** UPPER_SNAKE_CASE for compile-time constants
120
+ - **Interfaces:** PascalCase, no `I` prefix (`User` not `IUser`)
121
+
122
+ ### Error Handling
123
+ - Use custom error classes extending `Error`
124
+ - Never swallow errors silently
125
+ - Provide meaningful error messages
126
+ - Use try/catch with specific error types
127
+ - Validate inputs with Zod schemas
128
+
129
+ ### NestJS Specifics
130
+ - All commands extend `CommandRunner` from `nest-commander`
131
+ - Use Dependency Injection - never import services directly
132
+ - Register modules in `app.module.ts`
133
+ - Use `@Injectable()` decorator for services
134
+
135
+ ## 6. Configuration (kodu.json)
115
136
 
116
- Configuration structure:
117
137
  ```json
118
138
  {
119
139
  "llm": {
@@ -123,117 +143,82 @@ Configuration structure:
123
143
  "cleaner": {
124
144
  "whitelist": ["//!"],
125
145
  "keepJSDoc": true,
126
- "useGitignore": true,
127
- "ignore": []
146
+ "useGitignore": true
128
147
  },
129
148
  "packer": {
130
- "ignore": [
131
- "package-lock.json",
132
- "yarn.lock",
133
- "pnpm-lock.yaml",
134
- ".git",
135
- ".kodu",
136
- "node_modules",
137
- "dist",
138
- "coverage"
139
- ],
140
- "useGitignore": true,
141
- "contentBasedBinaryDetection": false
149
+ "ignore": ["*.lock", "node_modules", "dist"],
150
+ "useGitignore": true
142
151
  },
143
- "prompts": {
144
- "review": {
145
- "bug": "You are a strict code reviewer...\n\nDiff:\n{diff}",
146
- "style": "Check readability...\n\nDiff:\n{diff}",
147
- "security": "Find vulnerabilities...\n\nDiff:\n{diff}",
148
- "performance": "Check performance...\n\nDiff:\n{diff}"
149
- },
150
- "commit": "You generate Conventional Commit messages...\n\nDiff:\n{diff}"
152
+ "ops": {
153
+ "servers": {
154
+ "dev": {
155
+ "host": "example.com",
156
+ "port": 22,
157
+ "user": "ubuntu",
158
+ "sshKeyPath": "~/.ssh/id_rsa",
159
+ "paths": {
160
+ "apps": "/var/agent-apps",
161
+ "caddy": "/var/agent-apps/caddy"
162
+ }
163
+ }
164
+ }
151
165
  }
152
166
  }
153
167
  ```
154
168
 
155
- **Options:**
156
- - `llm.model`: Model identifier in format `"provider/model-name"` (e.g., `"openai/gpt-4o"`, `"anthropic/claude-4-5-sonnet"`, `"google/gemini-2.5-flash"`).
157
- - `llm.apiKeyEnv`: Environment variable name for API key (default: `"OPENAI_API_KEY"`).
158
-
159
- **Supported Providers:**
160
- Kodu supports 72+ providers through Mastra's model router:
161
-
162
- - **OpenAI**: `openai/gpt-4o`, `openai/gpt-4o-mini`, `openai/gpt-5`, etc.
163
- - **Anthropic**: `anthropic/claude-4-5-sonnet`, `anthropic/claude-opus-4-1`, etc.
164
- - **Google Gemini**: `google/gemini-2.5-flash`, `google/gemini-2.5-pro`, etc.
165
- - **xAI**: `xai/grok-4`, etc.
166
- - **OpenRouter**: `openrouter/anthropic/claude-haiku-4-5`, etc.
167
- - **And 65+ more providers**
168
-
169
- **API Key Environment Variables:**
170
- - OpenAI: `OPENAI_API_KEY`
171
- - Anthropic: `ANTHROPIC_API_KEY`
172
- - Google: `GOOGLE_API_KEY`
173
- - xAI: `XAI_API_KEY`
174
- - OpenRouter: `OPENROUTER_API_KEY`
175
- - Others: See provider documentation
176
-
177
- **Cleaner Whitelist Behavior:**
178
- - *System:* Automatically preserved: `@ts-ignore`, `@ts-expect-error`, `eslint-disable`, `prettier-ignore`, `biome-ignore`, `TODO`, `FIXME`.
179
- - *Biome:* Special support for `// biome-ignore ...` comments.
180
- - *User:* Custom list in `cleaner.whitelist` (e.g., `//!`).
181
-
182
- **Config Loading:**
183
- - Uses `lilconfig` to search for `kodu.json` in the current working directory.
184
- - Validated via Zod schema on every app startup.
185
- - App exits with error message if config is missing or invalid.
169
+ - Model format: `provider/model-name` (e.g., `openai/gpt-4o`, `anthropic/claude-4-5-sonnet`)
170
+ - API keys from env vars only (never store in config)
171
+ - Config validated via Zod on startup
186
172
 
187
173
  ## 7. Commands Reference
188
174
 
189
- ### 7.1. `kodu init`
190
- - Interactive setup wizard for creating `kodu.json`.
191
- - Creates `.kodu/` directory for prompt templates.
192
-
193
- ### 7.2. `kodu pack [options]`
194
- - Bundles project files into a single text file or clipboard.
195
- - Options:
196
- - `--copy`: Copy to clipboard instead of stdout.
197
- - `--template <name>`: Use prompt template from `.kodu/prompts/<name>.txt`.
198
- - `--out <file>`: Write to file instead of stdout.
199
- - Respects `.gitignore` and `packer.ignore` patterns.
200
- - Always displays token count and estimated cost.
201
-
202
- ### 7.3. `kodu clean [options]`
203
- - Removes comments from JS/TS files using AST parsing.
204
- - Options:
205
- - `--dry-run`: Show what would be removed without modifying files.
206
- - Supports: `.ts`, `.js`, `.tsx`, `.jsx`.
207
- - Deterministic (no AI) - uses `ts-morph` for safe parsing.
208
- - Preserves system comments and user whitelist.
209
-
210
- ### 7.4. `kodu review [options]`
211
- - Analyzes staged git diff via AI.
212
- - Options:
213
- - `--mode <mode>`: Review mode - `bug` (default), `style`, `security`, or custom mode from `prompts.review`. Standard modes (`bug`, `style`, `security`) are always available. Custom modes require configuration in `prompts.review` section of `kodu.json`.
214
- - `--ci`: CI/CD mode (no spinners, no buffering).
215
- - `--output <file>`: Save output to file.
216
- - Requires: Git repository, staged changes, API key.
217
-
218
- ### 7.5. `kodu commit [options]`
219
- - Generates Conventional Commit message from staged diff.
220
- - Options:
221
- - `--ci`: CI/CD mode (no spinners).
222
- - `--output <file>`: Save message to file.
223
- - Outputs to stdout (does NOT execute `git commit`).
224
- - Requires: Git repository, staged changes, API key.
175
+ | Command | Description | Key Options |
176
+ |---------|-------------|-------------|
177
+ | `kodu init` | Interactive setup wizard | - |
178
+ | `kodu pack` | Bundle files for LLM | `--copy`, `--template`, `--out` |
179
+ | `kodu clean` | Remove comments (AST-based) | `--dry-run` |
180
+ | `kodu review` | AI code review | `--mode`, `--ci`, `--output` |
181
+ | `kodu commit` | Generate commit message | `--ci`, `--output` |
182
+ | `kodu ops` | Remote server operations over SSH (JSON-only) | `sysinfo`, `env`, `routes`, `service` |
225
183
 
226
184
  ## 8. Critical Constraints
227
- 1. **No AI in Cleaner:** The `clean` command is purely deterministic (AST-based). Never use AI for code modification.
228
- 2. **Validation First:** The app must crash gracefully with a helpful message if `kodu.json` is invalid (handled by Zod).
229
- 3. **Secrets:** Never commit secrets. Assume `.env` usage for API keys. API keys are read from environment variables, not config files.
230
- 4. **Performance:** Be mindful of import costs. We use `tinyglobby` and `picocolors` to keep startup time low (< 0.5s target).
231
- 5. **AI Keys:** `llm.apiKeyEnv` (default `OPENAI_API_KEY`) must be set before running AI commands (`review`, `commit`).
232
- 6. **Diff Filtering:** `GitService` excludes paths from `packer.ignore` when building staged diff for AI to filter out lock/dist noise.
233
- 7. **Git Preconditions:** AI commands require a git repository and staged changes (otherwise exit with helpful message).
234
- 8. **Config Location:** `kodu.json` must be in the current working directory (searched via `lilconfig`).
235
-
236
- ## 9. Handling Uncertainties
237
- - If a task involves logic not defined in `docs/project_charter.md`, ask the user.
238
- - If unsure about a library, check Section 2 of this file. If not listed, prefer native Node.js APIs or check `docs/plan.md`.
239
- - When adding new dependencies, verify they align with the "Fresh & Modern" stack strategy and are not legacy libraries.
185
+
186
+ 1. **No AI in Cleaner:** `clean` command is deterministic (AST-based), never AI-generated
187
+ 2. **Validation First:** Invalid `kodu.json` causes graceful crash with Zod error
188
+ 3. **Secrets:** Never commit secrets. API keys from env vars only
189
+ 4. **Performance:** Mindful of import costs. Use lightweight libraries
190
+ 5. **Git Preconditions:** AI commands require git repo with staged changes
191
+ 6. **Config Location:** `kodu.json` must be in current working directory
192
+ 7. **AgentOps Output Contract:** `kodu ops` commands must return strict JSON (no spinners/colors/prompts)
193
+
194
+ ## 9. Development Workflow
195
+
196
+ ### Adding a New Command
197
+ 1. Create `src/commands/<name>/`
198
+ 2. Create `<name>.command.ts` and `<name>.module.ts`
199
+ 3. Implement `run()` extending `CommandRunner`
200
+ 4. Decorate with `@Command()` from `nest-commander`
201
+ 5. Register module in `app.module.ts`
202
+ 6. Test: `npm run build && node dist/main.js <name>`
203
+
204
+ ### Before Commit
205
+ Always run:
206
+ ```bash
207
+ npm run check
208
+ ```
209
+
210
+ This executes: TypeScript check + Biome lint + Knip dead code detection.
211
+
212
+ ## 10. Testing Strategy
213
+
214
+ - **Primary Gate:** Static analysis (TypeScript + Biome + Knip)
215
+ - **No Legacy Tests:** Project relies on strict static typing
216
+ - If tests exist: place in `__tests__/` or `*.test.ts` files
217
+ - Use Vitest or Jest (check package.json for actual test runner)
218
+
219
+ ## 11. Handling Uncertainties
220
+
221
+ - Unclear requirements? Ask the user first
222
+ - Library not in Tech Stack section? Prefer native Node.js APIs
223
+ - New dependency? Ensure it follows "Fresh & Modern" strategy
224
+ - Breaking changes? Create an OpenSpec proposal
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  **The AI-First CLI for Modern Developers**
6
6
 
7
- Generate contexts, clean code, review PRs, and draft commits—instantly.
7
+ Generate contexts, clean code, review PRs, draft commits, and run remote ops—instantly.
8
8
 
9
9
  [![npm version](https://img.shields.io/npm/v/kodu?style=flat-square&color=black)](https://www.npmjs.com/package/kodu)
10
10
  [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square&color=black)](LICENSE)
@@ -22,6 +22,7 @@ Generate contexts, clean code, review PRs, and draft commits—instantly.
22
22
  | Hitting token limits with comments | **`kodu clean`** strips noise deterministically |
23
23
  | Context switching for code reviews | **`kodu review`** checks logic inside your terminal |
24
24
  | Writing boring commit messages | **`kodu commit`** generates semantic git messages |
25
+ | SSHing around servers manually | **`kodu ops`** runs machine-readable remote operations |
25
26
 
26
27
  ---
27
28
 
@@ -88,6 +89,20 @@ kodu review --mode bug
88
89
  kodu review --mode security
89
90
  ```
90
91
 
92
+ ### 4. "I need my agent to inspect a server"
93
+ Run remote diagnostics and operations via `kodu ops` with strict JSON output.
94
+
95
+ ```bash
96
+ # Server health snapshot
97
+ kodu ops sysinfo dev
98
+
99
+ # Manage app env vars remotely
100
+ kodu ops env dev set my-app --key NODE_ENV --val production
101
+
102
+ # Read Caddy routes (raw Caddyfile)
103
+ kodu ops routes dev list
104
+ ```
105
+
91
106
  ---
92
107
 
93
108
  ## ⚙️ Configuration
@@ -108,17 +123,31 @@ Kodu creates a `kodu.json` in your root. It's pre-configured, but fully hackable
108
123
  "whitelist": ["//!"]
109
124
  },
110
125
  "packer": {
111
- // Files to strictly ignore
112
126
  "ignore": ["package-lock.json", "dist", "coverage"]
113
127
  },
128
+ "ops": {
129
+ "servers": {
130
+ "dev": {
131
+ "host": "example.com",
132
+ "port": 22,
133
+ "user": "ubuntu",
134
+ "sshKeyPath": "~/.ssh/id_rsa",
135
+ "paths": {
136
+ "apps": "/var/agent-apps",
137
+ "caddy": "/var/agent-apps/caddy"
138
+ }
139
+ }
140
+ }
141
+ },
114
142
  "prompts": {
115
- // Use your own prompts for reviews
116
143
  "review": {
117
144
  "bug": ".kodu/prompts/review-bug.md"
118
145
  }
119
146
  }
120
147
  }
121
148
  ```
149
+
150
+ `kodu ops` is designed for agents: responses are strict JSON (including errors), with no spinner/colors/prompts.
122
151
  </details>
123
152
 
124
153
  ---
@@ -0,0 +1,86 @@
1
+ {
2
+ "name": "kodu",
3
+ "version": "1.1.16",
4
+ "description": "High-performance CLI to prepare codebase for LLMs, automate reviews, and draft commits.",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/uxname/kodu.git"
8
+ },
9
+ "bugs": {
10
+ "url": "https://github.com/uxname/kodu/issues"
11
+ },
12
+ "homepage": "https://github.com/uxname/kodu#readme",
13
+ "keywords": [
14
+ "cli",
15
+ "ai",
16
+ "llm",
17
+ "developer-tools",
18
+ "productivity",
19
+ "typescript",
20
+ "openai",
21
+ "automation",
22
+ "code-review",
23
+ "context-window",
24
+ "git-tools"
25
+ ],
26
+ "private": false,
27
+ "license": "MIT",
28
+ "bin": {
29
+ "kodu": "dist/src/main.js"
30
+ },
31
+ "scripts": {
32
+ "________________ BUILD AND RUN ________________": "",
33
+ "build": "nest build && chmod +x dist/src/main.js",
34
+ "generate:schema": "ts-node scripts/generate-json-schema.ts",
35
+ "postbuild": "npm run generate:schema",
36
+ "start:prod": "node dist/main.js",
37
+ "new:command": "nest g -c nest-commander-schematics command",
38
+ "new:question": "nest g -c nest-commander-schematics question",
39
+ "________________ FORMAT AND LINT ________________": "",
40
+ "lint": "biome check",
41
+ "lint:fix": "biome check --write",
42
+ "lint:fix:unsafe": "biome check --write --unsafe",
43
+ "ts:check": "tsc --noEmit",
44
+ "knip": "knip --production",
45
+ "check": "run-p ts:check lint:fix knip",
46
+ "________________ OTHER ________________": "",
47
+ "prepare": "lefthook install"
48
+ },
49
+ "dependencies": {
50
+ "@inquirer/confirm": "^6.0.4",
51
+ "@inquirer/input": "^5.0.4",
52
+ "@inquirer/select": "^5.0.4",
53
+ "@mastra/core": "^1.0.4",
54
+ "@nestjs/common": "^11.0.1",
55
+ "@nestjs/core": "^11.0.1",
56
+ "clipboardy": "^5.0.2",
57
+ "execa": "^9.6.1",
58
+ "ignore": "^7.0.5",
59
+ "js-tiktoken": "^1.0.21",
60
+ "lilconfig": "^3.1.3",
61
+ "nest-commander": "^3.20.1",
62
+ "picocolors": "^1.1.1",
63
+ "reflect-metadata": "^0.2.2",
64
+ "rxjs": "^7.8.1",
65
+ "source-map-support": "^0.5.21",
66
+ "tinyglobby": "^0.2.15",
67
+ "ts-morph": "^24.0.0",
68
+ "yocto-spinner": "^1.0.0",
69
+ "zod": "^4.3.6"
70
+ },
71
+ "devDependencies": {
72
+ "@biomejs/biome": "^2.3.12",
73
+ "@nestjs/cli": "^11.0.0",
74
+ "@nestjs/schematics": "^11.0.0",
75
+ "@nestjs/testing": "^11.0.1",
76
+ "@types/node": "^22.10.7",
77
+ "knip": "^5.82.1",
78
+ "lefthook": "^2.0.15",
79
+ "nest-commander-schematics": "^3.2.0",
80
+ "npm-run-all": "^4.1.5",
81
+ "ts-loader": "^9.5.2",
82
+ "ts-node": "^10.9.2",
83
+ "tsconfig-paths": "^4.2.0",
84
+ "typescript": "^5.7.3"
85
+ }
86
+ }
@@ -11,6 +11,7 @@ const common_1 = require("@nestjs/common");
11
11
  const clean_module_1 = require("./commands/clean/clean.module");
12
12
  const commit_module_1 = require("./commands/commit/commit.module");
13
13
  const init_module_1 = require("./commands/init/init.module");
14
+ const ops_module_1 = require("./commands/ops/ops.module");
14
15
  const pack_module_1 = require("./commands/pack/pack.module");
15
16
  const review_module_1 = require("./commands/review/review.module");
16
17
  const config_module_1 = require("./core/config/config.module");
@@ -36,6 +37,7 @@ exports.AppModule = AppModule = __decorate([
36
37
  clean_module_1.CleanModule,
37
38
  review_module_1.ReviewModule,
38
39
  commit_module_1.CommitModule,
40
+ ops_module_1.OpsModule,
39
41
  ],
40
42
  })
41
43
  ], AppModule);
@@ -1 +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,6DAAyD;AACzD,mEAA+D;AAC/D,+DAA2D;AAC3D,4DAAwD;AACxD,mDAA+C;AAC/C,qDAAiD;AACjD,wDAAoD;AACpD,0EAAsE;AAiB/D,IAAM,SAAS,GAAf,MAAM,SAAS;CAAG,CAAA;AAAZ,8BAAS;oBAAT,SAAS;IAfrB,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;SACb;KACF,CAAC;GACW,SAAS,CAAG"}
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"}
@@ -38,6 +38,21 @@ let InitCommand = class InitCommand extends nest_commander_1.CommandRunner {
38
38
  const defaultConfig = {
39
39
  $schema: 'https://raw.githubusercontent.com/uxname/kodu/refs/heads/master/kodu.schema.json',
40
40
  llm: defaultLlmConfig,
41
+ ops: {
42
+ servers: {
43
+ dev: {
44
+ host: 'example.com',
45
+ port: 22,
46
+ user: 'ubuntu',
47
+ sshKeyPath: '~/.ssh/id_rsa',
48
+ description: 'Example AgentOps server',
49
+ paths: {
50
+ apps: '/var/agent-apps',
51
+ caddy: '/var/agent-apps/caddy',
52
+ },
53
+ },
54
+ },
55
+ },
41
56
  cleaner: {
42
57
  whitelist: ['//!'],
43
58
  keepJSDoc: true,
@@ -118,6 +133,7 @@ let InitCommand = class InitCommand extends nest_commander_1.CommandRunner {
118
133
  useGitignore: defaultConfig.packer.useGitignore,
119
134
  contentBasedBinaryDetection: defaultConfig.packer.contentBasedBinaryDetection,
120
135
  },
136
+ ops: defaultConfig.ops,
121
137
  prompts: {
122
138
  review: {
123
139
  bug: promptPaths.review.bug,