@mattgraba/dev-toolkit 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## v2.0.1 – 2026-07-04
+
+The actual first release of Dev Toolkit. (A `2.0.0` was briefly published before the hosted-service retirement below landed and has been removed from the registry — it still contained the retired service's default URL.)
+
+Includes everything under v2.0.0, plus:
+
+- **The public hosted service is retired and removed from the code.** The CLI ships no default API URL; server mode requires a self-hosted server via `DEV_TOOLKIT_API_URL` or `apiUrl` in config. BYOK is unaffected and primary.
+
+## v2.0.0 – 2026-07-03
+
+Renamed from **Dev Helper** (`@mattgraba/dev-helper`, `dev-helper`) to **Dev Toolkit** (`@mattgraba/dev-toolkit`, `devtk`), alongside a full security and architecture remediation. The audit that motivated this release is documented in [docs/RETROSPECTIVE.md](docs/RETROSPECTIVE.md).
+
+### Breaking
+
+- npm package: `@mattgraba/dev-helper` → `@mattgraba/dev-toolkit`
+- bin command: `dev-helper` → `devtk`
+- Config dir: `~/.dev-helper/` → `~/.dev-toolkit/` (existing config is migrated automatically on first run)
+- Env var: `DEV_HELPER_API_URL` → `DEV_TOOLKIT_API_URL`
+- Server API: JWTs now identify users by database id rather than username; tokens issued by v1 are not valid against the v2 server
+
+### Security
+
+- Removed the hardcoded JWT secret fallback; the server now refuses to start without `JWT_SECRET`
+- Global Express error handler; stack traces are no longer exposed outside development
+- Rate limiting is now applied after authentication, so per-user limits actually work (previously always per-IP); register and login have separate brute-force buckets; `/history` is rate-limited
+- Explicit string type-guards on auth inputs (closes NoSQL-operator-shaped payloads)
+- Local config and history files are written with owner-only permissions (0600)
+- Login password input is masked in the terminal
+- Context scanning skips credential-shaped filenames and is capped at 50 files
+- CLI no longer prints raw server response bodies on error
+
+### Fixed
+
+- **History now works in BYOK mode** — saved locally to `~/.dev-toolkit/history.json`; previously it silently did nothing without a login
+- Hosted-mode history was saved twice per command (once by the server route, once by the CLI); now saved once
+- Context file names appeared as `// undefined` in AI prompts due to a field-name mismatch between the scanner and prompt builders
+- History sorting referenced a field that didn't exist in the schema
+- The server Dockerfile and `dev` script pointed at a nonexistent entrypoint
+- The token-budget guard existed but was never invoked; it now runs on every AI request
+- Maintenance script crashed on launch (CommonJS in an ESM package)
+
+### Changed
+
+- **The public hosted service is retired.** The server and web client remain in the repo as a tested, self-hostable reference; the CLI no longer ships a default API URL (server mode requires `DEV_TOOLKIT_API_URL` or `apiUrl` in config). BYOK is unaffected and is the primary mode.
+- Six copy-pasted CLI command handlers and six copy-pasted server routes now share extracted helpers (`runAICommand`, `saveHistoryIfAuthed`, `withOpenAIErrorHandling`, `validateContextFiles`)
+- CLI config/token I/O consolidated from four independent implementations into one module
+- All prompt templates consolidated into the server's OpenAI service
+- `--context` (scan project files) and `--context-text` (plain text) are now orthogonal flags
+- Docs regenerated from the implementation; README is BYOK-first
+- Dead code removed (unreachable auth controller, unrelated leftover config, abandoned TypeScript stub)
+
+### Added
+
+- Structured boxed output for `analyze`: prompts request JSON (`issues[]` + `suggestion`), the CLI renders a Unicode-bordered result box with numbered, line-referenced issues, and the API returns the structured shape (ported from unreleased pre-v2 work that was stranded on a divergent branch)
+- Baseline test suites: 32 tests across server (auth flow, analyze route, per-user rate-limit regression) and CLI (config, local history, analysis parsing)
+- `.env.example` files for CLI and server
+- `docs/RETROSPECTIVE.md` — the v1 audit, kept as a learning record
+
+## v1.1.0 – 2026-02-03
+
+### Added
+- Bring Your Own OpenAI API Key (BYOK) support
+- `dev-helper config` command for local configuration
+- Optional hosted fallback for users without API keys
+
+### Changed
+- Authentication is no longer required when using a local API key

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Graba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# Dev Toolkit
+
+An AI-assisted developer CLI for analyzing errors, explaining and fixing code, generating boilerplate, and getting terminal commands — from your terminal, with your own OpenAI key.
+
+## Features
+
+- **BYOK-first** — bring your own OpenAI key; no account, no server, your code never touches third-party infrastructure beyond OpenAI itself
+- **Project-aware analysis** — optionally include surrounding files as context (gitignore-respecting, credential-file denylist, capped at 50 files / 20KB each)
+- **Six AI commands** — analyze, explain, fix, generate, scaffold, terminal
+- **Local history** — queries are saved to `~/.dev-toolkit/history.json` (BYOK mode), or server-side if you run the optional self-hosted server
+- **Suggestion-only terminal commands** — the `terminal` command prints suggested shell commands; it never executes anything
+
+## Installation
+
+```bash
+npm install -g @mattgraba/dev-toolkit
+```
+
+Verify:
+
+```bash
+devtk --help
+```
+
+## Quick Start (BYOK)
+
+```bash
+# Set your OpenAI API key (stored locally, owner-only file permissions)
+devtk config set-key sk-your-openai-api-key
+
+# Analyze a file
+devtk analyze -f ./src/buggy.js -l javascript
+```
+
+Your key is stored at `~/.dev-toolkit/config.json` and calls go directly to OpenAI. The `OPENAI_API_KEY` environment variable takes precedence over the config file if both are set.
+
+## CLI Reference
+
+| Command    | Description                                      | Key flags                       |
+| ---------- | ------------------------------------------------ | ------------------------------- |
+| `config`   | Manage configuration (`set-key`, `remove-key`, `show`) | —                          |
+| `analyze`  | Analyze buggy code → explanation + fix           | `-f <file>` `-l <language>`     |
+| `explain`  | Plain-English explanation of code                | `-f <file>` `-l <language>`     |
+| `fix`      | Corrected version of broken code                 | `-f <file>` `-l <language>` `-o <out>` |
+| `generate` | Generate code from a description                 | `-d <description>` `-o <out>`   |
+| `scaffold` | Scaffold a React component                       | `-n <name>` `-o <out>`          |
+| `terminal` | Suggest terminal commands for a goal             | `-g <goal>`                     |
+| `history`  | View past queries (local file or server)         | —                               |
+| `login`    | Authenticate with a self-hosted server (optional) | —                              |
+
+### Context-aware mode
+
+```bash
+devtk analyze -f ./src/index.js -l javascript --context
+```
+
+`--context` scans nearby `.js`/`.ts`/`.json` files and includes them in the prompt. The scan respects `.gitignore`, skips dotfiles and credential-shaped filenames (`*.pem`, `*.key`, `id_rsa*`, `*credential*`, `*secret*`, …), and is capped at 50 files of up to 20KB each.
+
+## Optional: Self-Hosted Server
+
+The repo includes a full backend (Express API with JWT auth, per-user rate limiting, and MongoDB history) and a React web client. **There is no public hosted instance** — the server exists as a tested, self-hostable reference implementation and a demonstration of the project's backend engineering. If you run your own:
+
+```bash
+export DEV_TOOLKIT_API_URL=https://your-server.example.com
+devtk login
+devtk analyze -f ./src/buggy.js -l javascript
+```
+
+See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for server setup. BYOK is the way to use the tool day to day.
+
+| | BYOK | Self-hosted server |
+|---|---|---|
+| Account required | No | Yes (on your server) |
+| OpenAI key | Yours, local | Your server's |
+| History | Local file | Server + web UI |
+| Privacy | Key and code stay local (OpenAI only) | Requests pass through your API |
+
+## Architecture
+
+```
+BYOK:         CLI ──────────────────────────────▶ OpenAI API
+
+Self-hosted:  CLI ──┐
+                    ├──▶ Express API (JWT auth, per-user rate limiting)
+        Web client ─┘         │
+                              ├──▶ OpenAI API
+                              └──▶ MongoDB (users, history)
+```
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full picture, and [docs/RETROSPECTIVE.md](docs/RETROSPECTIVE.md) for an honest audit of the v1 codebase and what v2 fixed.
+
+## Configuration
+
+Config file: `~/.dev-toolkit/config.json` (created with owner-only permissions; migrated automatically from `~/.dev-helper/` if you're upgrading).
+
+| Field | Purpose |
+|-------|---------|
+| `openaiApiKey` | Your OpenAI key (BYOK mode) |
+| `token` | JWT from `devtk login` (self-hosted server mode) |
+| `apiUrl` | Your self-hosted server's URL |
+
+Environment variables: `OPENAI_API_KEY` (overrides config key), `DEV_TOOLKIT_API_URL` (overrides API URL).
+
+For self-hosting the server, see [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
+
+## Development
+
+```bash
+npm install          # CLI deps
+npm test             # CLI tests
+cd server && npm install && npm test   # server tests
+```
+
+## Contributing
+
+Pull requests are welcome. Please open an issue first to discuss proposed changes.
+
+## License
+
+MIT © [Matt Graba](https://mattgraba.com)

package/bin/devtk.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+// This is the npm bin entry point
+// It simply loads the CLI from the cli directory
+import '../cli/cli.js';

package/cli/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// ^ shebang line allows the script to be run directly from the terminal
+import { Command } from 'commander';
+import 'dotenv/config';
+const program = new Command();
+
+// Import per-command handlers
+import handleAnalyze from './commands/analyzeCommand.js';
+import handleExplain from './commands/explainCommand.js';
+import handleFix from './commands/fixCommand.js';
+import handleGenerate from './commands/generateCommand.js';
+import handleScaffold from './commands/scaffoldCommand.js';
+import handleTerminal from './commands/terminalCommand.js';
+import handleLogin from './commands/loginCommand.js';
+import handleHistory from './commands/historyCommand.js';
+import handleConfig from './commands/configCommand.js';
+
+// CLI Metadata: defines basic information when a user runs `devtk --help`
+program
+  .name('devtk')
+  .description('Dev Toolkit — a developer CLI assistant powered by AI')
+  .version('2.0.1');
+
+// Register commands
+handleAnalyze(program);
+handleExplain(program);
+handleFix(program);
+handleGenerate(program);
+handleHistory(program);
+handleLogin(program);
+handleScaffold(program);
+handleTerminal(program);
+handleConfig(program);
+
+// Triggers the CLI to interpret the command-line arguments passed by the user (e.g., `devtk analyze`)
+program.parse(process.argv);

package/cli/commands/analyzeCommand.js

@@ -0,0 +1,21 @@
+import { handleAnalyzeBasic, handleAnalyzeWithContext } from './analyzeHandlers.js';
+import handleWithContext from '../utils/contextHandlerWrapper.js';
+
+export default (program) => {
+  program
+    .command('analyze')
+    .alias('a')
+    .description('Analyze code errors and receive an AI explanation and fix')
+    .usage('-f <file> -l <language> [--context]')
+    .requiredOption('-f, --file <path>', 'Path to code file with an error')
+    .requiredOption('-l, --language <name>', 'Programming language')
+    .option('--context', 'Include context from surrounding project files')
+    .showHelpAfterError(true)
+    .action((options) => {
+      handleWithContext({
+        options,
+        handleBasic: handleAnalyzeBasic,
+        handleWithContext: handleAnalyzeWithContext,
+      });
+    });
+};

package/cli/commands/analyzeHandlers.js

@@ -0,0 +1,55 @@
+import fs from 'fs';
+import path from 'path';
+
+import { checkFileExists } from '../utils/fsUtils.js';
+import { scanFiles } from '../utils/fileScanner.js';
+import saveToHistory from '../utils/historySaver.js';
+import runAICommand from '../utils/commandRunner.js';
+import { renderAnalysisBox, parseAnalysisJSON } from '../utils/formatBox.js';
+import { analyzeCode } from '../services/localOpenAI.js';
+
+async function runAnalyze({ filePath, language, contextFiles }) {
+  const errorText = fs.readFileSync(path.resolve(filePath), 'utf-8');
+  const withContext = contextFiles.length > 0;
+
+  const data = await runAICommand({
+    spinnerText: `Analyzing ${filePath}${withContext ? ' with context' : ''}...`,
+    successText: withContext ? 'Contextual analysis complete ✅' : 'Analysis complete ✅',
+    failText: 'Analysis failed',
+    localFn: () => analyzeCode({ errorText, language, contextFiles }),
+    endpoint: '/analyze',
+    payload: { errorText, language, contextFiles },
+  });
+  if (!data) return;
+
+  // BYOK returns the raw model text; the server returns parsed { issues, suggestion }
+  const parsed = data.raw
+    ? parseAnalysisJSON(data.raw)
+    : { issues: data.issues || [], suggestion: data.suggestion || '' };
+
+  console.log('');
+  renderAnalysisBox({ filePath, ...parsed });
+  console.log('');
+
+  await saveToHistory({
+    command: 'analyze',
+    input: errorText,
+    output: JSON.stringify(parsed),
+  });
+}
+
+async function handleAnalyzeBasic({ filePath, language }) {
+  if (!checkFileExists(filePath)) return;
+  await runAnalyze({ filePath, language, contextFiles: [] });
+}
+
+async function handleAnalyzeWithContext({ filePath, language }) {
+  if (!checkFileExists(filePath)) return;
+  const contextFiles = await scanFiles({ directory: path.dirname(filePath) });
+  await runAnalyze({ filePath, language, contextFiles });
+}
+
+export {
+  handleAnalyzeBasic,
+  handleAnalyzeWithContext,
+};

package/cli/commands/configCommand.js

@@ -0,0 +1,33 @@
+import { handleSetKey, handleRemoveKey, handleShowConfig } from './configHandlers.js';
+
+export default (program) => {
+  const config = program
+    .command('config')
+    .description('Manage Dev Toolkit configuration');
+
+  config
+    .command('set-key <api-key>')
+    .description('Set your OpenAI API key for BYOK (Bring Your Own Key) mode')
+    .action((apiKey) => {
+      handleSetKey(apiKey);
+    });
+
+  config
+    .command('remove-key')
+    .description('Remove your stored OpenAI API key')
+    .action(() => {
+      handleRemoveKey();
+    });
+
+  config
+    .command('show')
+    .description('Show current configuration')
+    .action(() => {
+      handleShowConfig();
+    });
+
+  // Default action when just running `devtk config`
+  config.action(() => {
+    handleShowConfig();
+  });
+};

package/cli/commands/configHandlers.js

@@ -0,0 +1,96 @@
+import chalk from 'chalk';
+import {
+  getConfig,
+  setConfigValue,
+  removeConfigValue,
+  getOpenAIKey,
+  maskKey,
+  CONFIG_FILE,
+} from '../utils/configManager.js';
+
+function handleSetKey(apiKey) {
+  if (!apiKey || typeof apiKey !== 'string' || !apiKey.trim()) {
+    console.error(chalk.red('Please provide a valid API key.'));
+    process.exit(1);
+  }
+
+  const trimmedKey = apiKey.trim();
+
+  if (!trimmedKey.startsWith('sk-')) {
+    console.warn(chalk.yellow('Warning: OpenAI API keys typically start with "sk-".'));
+  }
+
+  setConfigValue('openaiApiKey', trimmedKey);
+  console.log(chalk.green('OpenAI API key saved successfully.'));
+  console.log(chalk.dim(`Key: ${maskKey(trimmedKey)}`));
+  console.log(chalk.dim(`Location: ${CONFIG_FILE}`));
+  console.log(chalk.cyan('\nYou can now use devtk commands without logging in.'));
+}
+
+function handleRemoveKey() {
+  const config = getConfig();
+  if (!config.openaiApiKey) {
+    console.log(chalk.yellow('No API key configured.'));
+    return;
+  }
+
+  removeConfigValue('openaiApiKey');
+  console.log(chalk.green('OpenAI API key removed.'));
+  console.log(chalk.dim('You will need to login or set a new key to use AI commands.'));
+}
+
+function handleShowConfig() {
+  const config = getConfig();
+  const envKey = process.env.OPENAI_API_KEY;
+
+  console.log(chalk.cyan('\nDev Toolkit Configuration\n'));
+
+  // Token status
+  if (config.token) {
+    console.log(chalk.green('  Auth token: ') + chalk.dim('configured'));
+  } else {
+    console.log(chalk.yellow('  Auth token: ') + chalk.dim('not set'));
+  }
+
+  // API URL
+  if (process.env.DEV_TOOLKIT_API_URL) {
+    console.log(chalk.green('  API URL: ') + process.env.DEV_TOOLKIT_API_URL + chalk.dim(' (from env var)'));
+  } else if (config.apiUrl) {
+    console.log(chalk.green('  API URL: ') + config.apiUrl);
+  } else {
+    console.log(chalk.dim('  API URL: not set (only needed for a self-hosted server)'));
+  }
+
+  // OpenAI key status
+  console.log('');
+  if (envKey) {
+    console.log(chalk.green('  OpenAI key: ') + maskKey(envKey) + chalk.dim(' (from OPENAI_API_KEY env var)'));
+  } else if (config.openaiApiKey) {
+    console.log(chalk.green('  OpenAI key: ') + maskKey(config.openaiApiKey) + chalk.dim(' (from config file)'));
+  } else {
+    console.log(chalk.yellow('  OpenAI key: ') + chalk.dim('not set'));
+  }
+
+  // Mode explanation
+  console.log('');
+  const localKey = getOpenAIKey();
+  if (localKey) {
+    console.log(chalk.green('  Mode: ') + 'BYOK (using your own OpenAI key)');
+    console.log(chalk.dim('  AI commands will call OpenAI directly - no login required.'));
+  } else if (config.token) {
+    console.log(chalk.green('  Mode: ') + 'Self-hosted server (logged in)');
+    console.log(chalk.dim('  AI commands will use the configured API URL.'));
+  } else {
+    console.log(chalk.yellow('  Mode: ') + 'Not configured');
+    console.log(chalk.dim('  Run "devtk config set-key <key>" to get started.'));
+  }
+
+  console.log('');
+  console.log(chalk.dim(`Config file: ${CONFIG_FILE}`));
+}
+
+export {
+  handleSetKey,
+  handleRemoveKey,
+  handleShowConfig,
+};

package/cli/commands/explainCommand.js

@@ -0,0 +1,21 @@
+import { handleExplainBasic, handleExplainWithContext } from './explainHandlers.js';
+import handleWithContext from '../utils/contextHandlerWrapper.js';
+
+export default (program) => {
+  program
+    .command('explain')
+    .alias('e')
+    .description('Explain a code file line by line using AI')
+    .usage('-f <file> -l <language> [--context]')
+    .requiredOption('-f, --file <path>', 'Path to the code file to explain')
+    .requiredOption('-l, --language <name>', 'Programming language')
+    .option('--context', 'Include context from surrounding project files')
+    .showHelpAfterError(true)
+    .action((options) => {
+      handleWithContext({
+        options,
+        handleBasic: handleExplainBasic,
+        handleWithContext: handleExplainWithContext,
+      });
+    });
+};

package/cli/commands/explainHandlers.js

@@ -0,0 +1,48 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+
+import { checkFileExists } from '../utils/fsUtils.js';
+import { scanFiles } from '../utils/fileScanner.js';
+import saveToHistory from '../utils/historySaver.js';
+import runAICommand from '../utils/commandRunner.js';
+import { explainCode } from '../services/localOpenAI.js';
+
+async function runExplain({ filePath, language, contextFiles }) {
+  const codeSnippet = fs.readFileSync(path.resolve(filePath), 'utf-8');
+  const withContext = contextFiles.length > 0;
+
+  const data = await runAICommand({
+    spinnerText: `Explaining ${filePath}${withContext ? ' with context' : ''}...`,
+    successText: withContext ? 'Contextual explanation complete ✅' : 'Explanation complete ✅',
+    failText: 'Explanation failed',
+    localFn: () => explainCode({ codeSnippet, language, contextFiles }),
+    endpoint: '/explain',
+    payload: { codeSnippet, language, contextFiles },
+  });
+  if (!data) return;
+
+  console.log(chalk.green('\n📖 Explanation:\n'), data.explanation);
+
+  await saveToHistory({
+    command: 'explain',
+    input: codeSnippet,
+    output: data.explanation,
+  });
+}
+
+async function handleExplainBasic({ filePath, language }) {
+  if (!checkFileExists(filePath)) return;
+  await runExplain({ filePath, language, contextFiles: [] });
+}
+
+async function handleExplainWithContext({ filePath, language }) {
+  if (!checkFileExists(filePath)) return;
+  const contextFiles = await scanFiles({ directory: path.dirname(filePath) });
+  await runExplain({ filePath, language, contextFiles });
+}
+
+export {
+  handleExplainBasic,
+  handleExplainWithContext,
+};

package/cli/commands/fixCommand.js

@@ -0,0 +1,23 @@
+import { handleFixBasic, handleFixWithContext } from './fixHandlers.js';
+import handleWithContext from '../utils/contextHandlerWrapper.js';
+
+export default (program) => {
+  program
+    .command('fix')
+    .alias('f')
+    .description('Fix buggy code using AI-generated improvements')
+    .usage('-f <file> -l <language> [--context] [--output <path>]')
+    .requiredOption('-f, --file <path>', 'Path to the file containing the buggy code')
+    .requiredOption('-l, --language <name>', 'Programming language (e.g., javascript, python)')
+    .option('--context', 'Include surrounding project files for more accurate fixes')
+    .option('--output <path>', 'Optional path to save the fixed output file')
+    .showHelpAfterError(true)
+    .action((options) => {
+      const { output, ...rest } = options;
+      handleWithContext({
+        options: { ...rest, outputPath: output },
+        handleBasic: handleFixBasic,
+        handleWithContext: handleFixWithContext,
+      });
+    });
+};

package/cli/commands/fixHandlers.js

@@ -0,0 +1,54 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+
+import { checkFileExists } from '../utils/fsUtils.js';
+import { scanFiles } from '../utils/fileScanner.js';
+import saveToHistory from '../utils/historySaver.js';
+import runAICommand from '../utils/commandRunner.js';
+import { fixCode } from '../services/localOpenAI.js';
+
+async function runFix({ filePath, language, outputPath, contextFiles }) {
+  const codeSnippet = fs.readFileSync(path.resolve(filePath), 'utf-8');
+  const withContext = contextFiles.length > 0;
+
+  const data = await runAICommand({
+    spinnerText: `Fixing ${filePath}${withContext ? ' with context' : ''}...`,
+    successText: withContext ? 'Fix with context complete ✅' : 'Fix complete ✅',
+    failText: 'Fix failed',
+    localFn: () => fixCode({ codeSnippet, language, contextFiles }),
+    endpoint: '/fix',
+    payload: { codeSnippet, language, contextFiles },
+  });
+  if (!data) return;
+
+  const { fixedCode } = data;
+  if (outputPath) {
+    fs.writeFileSync(outputPath, fixedCode, 'utf-8');
+    console.log(chalk.blue(`\n✅ Saved to ${outputPath}`));
+  } else {
+    console.log(chalk.green('\n🔧 Fixed Code:\n'), fixedCode);
+  }
+
+  await saveToHistory({
+    command: 'fix',
+    input: codeSnippet,
+    output: fixedCode,
+  });
+}
+
+async function handleFixBasic({ filePath, language, outputPath }) {
+  if (!checkFileExists(filePath)) return;
+  await runFix({ filePath, language, outputPath, contextFiles: [] });
+}
+
+async function handleFixWithContext({ filePath, language, outputPath }) {
+  if (!checkFileExists(filePath)) return;
+  const contextFiles = await scanFiles({ directory: path.dirname(filePath) });
+  await runFix({ filePath, language, outputPath, contextFiles });
+}
+
+export {
+  handleFixBasic,
+  handleFixWithContext,
+};

package/cli/commands/generateCommand.js

@@ -0,0 +1,19 @@
+import { handleGenerateBasic } from './generateHandlers.js';
+
+export default (program) => {
+  program
+    .command('generate')
+    .alias('g')
+    .description('Generate code from an AI-assisted text prompt')
+    .usage('-d <description> [--output <path>] [--name <value>] [--template <value>]')
+    .requiredOption('-d, --description <text>', 'Natural language description of the desired code')
+    .option('--output <path>', 'Optional path to save generated code')
+    .option('--name <value>', 'Optional name for generated component (if applicable)')
+    .option('--template <value>', 'Optional template or structure type')
+    .showHelpAfterError(true)
+    .action((options) => {
+      const { output, ...rest } = options;
+      const fixedOptions = { ...rest, outputPath: output };
+      handleGenerateBasic(fixedOptions);
+    });
+};

package/cli/commands/generateHandlers.js

@@ -0,0 +1,38 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+
+import saveToHistory from '../utils/historySaver.js';
+import runAICommand from '../utils/commandRunner.js';
+import { generateCode } from '../services/localOpenAI.js';
+
+async function handleGenerateBasic({ description, outputPath }) {
+  const data = await runAICommand({
+    spinnerText: 'Generating code...',
+    successText: 'Generation complete ✅',
+    failText: 'Generation failed',
+    localFn: () => generateCode({ description }),
+    endpoint: '/generate',
+    payload: { description },
+  });
+  if (!data) return;
+
+  const { generatedCode } = data;
+  if (outputPath) {
+    const fullPath = path.resolve(outputPath);
+    fs.writeFileSync(fullPath, generatedCode, 'utf-8');
+    console.log(chalk.blue(`\n✅ Saved to ${fullPath}`));
+  } else {
+    console.log(chalk.green('\n🧠 Generated Code:\n'), generatedCode);
+  }
+
+  await saveToHistory({
+    command: 'generate',
+    input: description,
+    output: generatedCode,
+  });
+}
+
+export {
+  handleGenerateBasic,
+};