@mattgraba/dev-toolkit 2.0.1

package/cli/commands/historyCommand.js

@@ -0,0 +1,14 @@
+import handleHistory from './historyHandlers.js';
+
+export default (program) => {
+  program
+    .command('history')
+    .alias('h')
+    .description('View your saved command output history')
+    .usage('[--userId <id>]')
+    .option('--userId <id>', 'Optional user ID filter for history')
+    .showHelpAfterError(true)
+    .action((options) => {
+      handleHistory(options);
+    });
+};

package/cli/commands/historyHandlers.js

@@ -0,0 +1,56 @@
+import axios from 'axios';
+import chalk from 'chalk';
+import ora from 'ora';
+
+import handleCliError from '../utils/errorHandler.js';
+import { getToken, apiEndpoint } from '../utils/configManager.js';
+import { readLocalHistory, HISTORY_FILE } from '../utils/localHistory.js';
+
+function printEntries(entries) {
+  entries.forEach((entry, i) => {
+    console.log(chalk.cyan(`\n📌 Entry ${i + 1}: [${entry.command}]`));
+    console.log(chalk.gray(`> Input:\n${entry.input}`));
+    console.log(chalk.green(`> Output:\n${entry.output}`));
+  });
+}
+
+async function handleHistory() {
+  const token = getToken();
+
+  // BYOK / not logged in: read the local history file
+  if (!token) {
+    const entries = readLocalHistory();
+    if (!entries.length) {
+      console.log(chalk.yellow('\n📭 No saved history found.'));
+      console.log(chalk.dim(`Local history is saved to ${HISTORY_FILE} as you run commands.\n`));
+      return;
+    }
+    console.log(chalk.dim(`\nLocal history (${HISTORY_FILE}):`));
+    printEntries(entries);
+    return;
+  }
+
+  // Hosted mode: fetch from the server
+  let spinner;
+  try {
+    spinner = ora('Fetching your history...').start();
+
+    const res = await axios.get(apiEndpoint('/history'), {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    spinner.succeed('History retrieved ✅');
+
+    const entries = res.data;
+    if (!entries.length) {
+      console.log(chalk.yellow('\n📭 No saved history found.\n'));
+      return;
+    }
+
+    printEntries(entries);
+  } catch (err) {
+    handleCliError(spinner, err, 'Failed to fetch history');
+  }
+}
+
+export default handleHistory;

package/cli/commands/loginCommand.js

@@ -0,0 +1,13 @@
+import handleLogin from './loginHandlers.js';
+
+export default (program) => {
+  program
+    .command('login')
+    .alias('l')
+    .description('Authenticate with your user ID to enable secured commands')
+    .usage('')
+    .showHelpAfterError(true)
+    .action(() => {
+      handleLogin();
+    });
+};

package/cli/commands/loginHandlers.js

@@ -0,0 +1,48 @@
+import readline from 'readline';
+import axios from 'axios';
+import chalk from 'chalk';
+import ora from 'ora';
+import handleCliError from '../utils/errorHandler.js';
+import promptPassword from '../utils/promptPassword.js';
+import { apiEndpoint, setToken } from '../utils/configManager.js';
+
+async function handleLogin() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  let spinner;
+  try {
+    console.log(chalk.cyan('\n🔐 Dev Toolkit Login\n'));
+
+    const username = await new Promise(resolve =>
+      rl.question(chalk.white('Username: '), answer => resolve(answer.trim()))
+    );
+    rl.close();
+
+    // Masked input — the password is never echoed to the terminal
+    const password = (await promptPassword(chalk.white('Password: '))).trim();
+
+    if (!username || !password) {
+      console.error(chalk.red('❌ Username and password are required.'));
+      process.exit(1);
+    }
+
+    spinner = ora('Logging in...').start();
+
+    const res = await axios.post(apiEndpoint('/auth/login'), { username, password });
+    setToken(res.data.token);
+
+    spinner.succeed(chalk.green('Login successful! Token saved.'));
+  } catch (err) {
+    if (spinner) {
+      handleCliError(spinner, err, 'Login failed');
+    } else {
+      console.error(chalk.red('❌ Error:'), err.response?.data?.error || err.message);
+    }
+    rl.close();
+  }
+}
+
+export default handleLogin;

package/cli/commands/scaffoldCommand.js

@@ -0,0 +1,18 @@
+import { handleScaffoldBasic } from './scaffoldHandlers.js';
+
+export default (program) => {
+  program
+    .command('scaffold')
+    .alias('s')
+    .description('Scaffold a basic project component or template')
+    .usage('-n <name> [--output <path>]')
+    .requiredOption('-n, --name <text>', 'Name of the component or feature')
+    .option('--output <path>', 'Optional file path to save scaffolded output')
+    .showHelpAfterError(true)
+    .action((options) => {
+      const { output, ...rest } = options;
+      const fixedOptions = { ...rest, outputPath: output };
+      handleScaffoldBasic(fixedOptions);
+    });
+};
+

package/cli/commands/scaffoldHandlers.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 { scaffoldCode as scaffoldCodeLocal } from '../services/localOpenAI.js';
+
+async function handleScaffoldBasic({ name, outputPath }) {
+  const data = await runAICommand({
+    spinnerText: `Scaffolding ${name}...`,
+    successText: 'Scaffold complete ✅',
+    failText: 'Scaffold failed',
+    localFn: () => scaffoldCodeLocal({ name }),
+    endpoint: '/scaffold',
+    payload: { name },
+  });
+  if (!data) return;
+
+  const { scaffoldCode } = data;
+  if (outputPath) {
+    const fullPath = path.resolve(outputPath);
+    fs.writeFileSync(fullPath, scaffoldCode, 'utf-8');
+    console.log(chalk.blue(`\n✅ Saved to ${fullPath}`));
+  } else {
+    console.log(chalk.green('\n🧱 Scaffolded Code:\n'), scaffoldCode);
+  }
+
+  await saveToHistory({
+    command: 'scaffold',
+    input: name,
+    output: scaffoldCode,
+  });
+}
+
+export {
+  handleScaffoldBasic,
+};

package/cli/commands/terminalCommand.js

@@ -0,0 +1,21 @@
+import { handleTerminalBasic, handleTerminalWithContext } from './terminalHandlers.js';
+import handleWithContext from '../utils/contextHandlerWrapper.js';
+
+export default (program) => {
+  program
+    .command('terminal')
+    .alias('t')
+    .description('Get terminal commands to set up or debug your project')
+    .usage('--goal <text> [--context-text <text>] [--context]')
+    .requiredOption('-g, --goal <text>', 'Project goal or setup intention')
+    .option('--context-text <text>', 'Optional plain text context (e.g. dependencies)')
+    .option('--context', 'Include full file context from the project')
+    .showHelpAfterError(true)
+    .action((options) => {
+      handleWithContext({
+        options,
+        handleBasic: handleTerminalBasic,
+        handleWithContext: handleTerminalWithContext,
+      });
+    });
+};

package/cli/commands/terminalHandlers.js

@@ -0,0 +1,52 @@
+import chalk from 'chalk';
+
+import { scanFiles } from '../utils/fileScanner.js';
+import saveToHistory from '../utils/historySaver.js';
+import runAICommand from '../utils/commandRunner.js';
+import { getTerminalCommands } from '../services/localOpenAI.js';
+
+function stripCodeFences(commands) {
+  return commands.replace(/```[a-zA-Z]*\n?/, '').replace(/```$/, '').trim();
+}
+
+async function runTerminal({ goal, contextText = '', contextFiles = [] }) {
+  const data = await runAICommand({
+    spinnerText: `Getting terminal commands${contextFiles.length ? ' with context' : ''}...`,
+    successText: 'Terminal generation complete ✅',
+    failText: 'Terminal command generation failed',
+    localFn: () => getTerminalCommands({ goal, context: contextText, contextFiles }),
+    endpoint: '/terminal',
+    payload: { goal, context: contextText, contextFiles },
+  });
+  if (!data) return;
+
+  if (!data.commands) {
+    console.error(chalk.red('❌ No terminal commands returned'));
+    return;
+  }
+
+  const commands = stripCodeFences(data.commands);
+
+  console.log(chalk.green('\n💻 Suggested terminal commands:\n'));
+  console.log(commands);
+
+  await saveToHistory({
+    command: 'terminal',
+    input: goal,
+    output: commands,
+  });
+}
+
+async function handleTerminalBasic({ goal, contextText }) {
+  await runTerminal({ goal, contextText });
+}
+
+async function handleTerminalWithContext({ goal, contextText }) {
+  const contextFiles = await scanFiles({ directory: '.' });
+  await runTerminal({ goal, contextText, contextFiles });
+}
+
+export {
+  handleTerminalBasic,
+  handleTerminalWithContext,
+};

package/cli/services/localOpenAI.js

@@ -0,0 +1,140 @@
+import { OpenAI } from 'openai';
+import { getOpenAIKey } from '../utils/configManager.js';
+
+let openaiClient = null;
+
+function getClient() {
+  if (!openaiClient) {
+    const apiKey = getOpenAIKey();
+    if (!apiKey) {
+      throw new Error('No OpenAI API key configured. Run: devtk config set-key <your-key>');
+    }
+    openaiClient = new OpenAI({ apiKey });
+  }
+  return openaiClient;
+}
+
+function resetClient() {
+  openaiClient = null;
+}
+
+async function sendPrompt(prompt, systemPrompt = 'You are a senior software engineer.') {
+  const completion = await getClient().chat.completions.create({
+    model: 'gpt-4',
+    messages: [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: prompt },
+    ],
+    temperature: 0.7,
+    max_tokens: 1500,
+  });
+  return completion.choices[0].message.content;
+}
+
+async function analyzeCode({ errorText, language = 'JavaScript', contextFiles = [] }) {
+  const contextText = contextFiles.map(f => `// ${f.name}\n${f.content}`).join('\n\n');
+
+  const prompt = `Analyze the following ${language} code for bugs, errors, and issues.
+
+\`\`\`${language}
+${errorText}
+\`\`\`
+
+${contextText ? `Context files:\n\n${contextText}\n` : ''}
+Respond ONLY with valid JSON in this exact format (no markdown fences, no extra text):
+{
+  "issues": [
+    { "line": <line_number_or_null>, "title": "<short title>", "detail": "<1-2 sentence explanation>" }
+  ],
+  "suggestion": "<concise fix recommendation covering all issues>"
+}`;
+
+  const fullResponse = await sendPrompt(prompt, 'You are a senior software engineer. Always respond with valid JSON only.');
+  return { raw: fullResponse };
+}
+
+async function explainCode({ codeSnippet, language = 'JavaScript', contextFiles = [] }) {
+  const contextText = contextFiles.map(f => `// ${f.name}\n${f.content}`).join('\n\n');
+
+  const prompt = `
+You are an expert software engineer.
+Explain the following ${language} code snippet line by line in beginner-friendly terms:
+
+\`\`\`${language}
+${codeSnippet}
+\`\`\`
+
+${contextText ? `Additional context:\n\n${contextText}` : ''}
+`;
+
+  const explanation = await sendPrompt(prompt);
+  return { explanation };
+}
+
+async function fixCode({ codeSnippet, language = 'JavaScript', contextFiles = [] }) {
+  const contextText = contextFiles.map(f => `// ${f.name}\n${f.content}`).join('\n\n');
+
+  const prompt = `
+You are a software engineer. Fix the following ${language} code and return only the corrected version:
+
+\`\`\`${language}
+${codeSnippet}
+\`\`\`
+
+${contextText ? `Here is additional context:\n\n${contextText}` : ''}
+`;
+
+  const fixedCode = await sendPrompt(prompt);
+  return { fixedCode };
+}
+
+async function generateCode({ description, language = 'JavaScript', context = '', fileType = '' }) {
+  const prompt = `
+Generate ${fileType ? fileType + ' ' : ''}code in ${language} for the following description:
+
+"${description}"
+
+Output preference: code only, no explanation
+
+${context ? `\n\nAdditional context:\n${context}` : ''}
+`;
+
+  const generatedCode = await sendPrompt(prompt);
+  return { generatedCode };
+}
+
+async function scaffoldCode({ name }) {
+  const prompt = `
+Scaffold a modern React component named "${name}" using best practices.
+Include comments and clear structure.
+`;
+
+  const scaffoldCode = await sendPrompt(prompt);
+  return { scaffoldCode };
+}
+
+async function getTerminalCommands({ goal, context = '', contextFiles = [] }) {
+  const contextFileText = contextFiles.map(f => `// ${f.name}\n${f.content}`).join('\n\n');
+
+  const prompt = `
+You're a DevOps engineer. Provide the terminal commands to accomplish the following:
+
+"${goal}"
+
+${context ? `\n\nProject context:\n${context}` : ''}
+${contextFileText ? `\n\nProject files:\n${contextFileText}` : ''}
+`;
+
+  const commands = await sendPrompt(prompt);
+  return { commands };
+}
+
+export {
+  analyzeCode,
+  explainCode,
+  fixCode,
+  generateCode,
+  scaffoldCode,
+  getTerminalCommands,
+  resetClient,
+};

package/cli/utils/commandRunner.js

@@ -0,0 +1,55 @@
+// cli/utils/commandRunner.js
+// Shared execution path for every AI command: resolve auth mode (BYOK vs
+// hosted), run the request behind a spinner, handle errors consistently.
+// Replaces the near-identical block previously copy-pasted into all six
+// command handlers.
+
+import axios from 'axios';
+import chalk from 'chalk';
+import ora from 'ora';
+import { hasLocalKey, getToken, apiEndpoint } from './configManager.js';
+import handleCliError from './errorHandler.js';
+
+function exitWithAuthGuidance() {
+  console.error(chalk.red('❌ No API key or login found.'));
+  console.log(chalk.dim('Run "devtk config set-key <your-openai-key>" to use your own key.'));
+  console.log(chalk.dim('Or, if you self-host the Dev Toolkit server, run "devtk login".'));
+  process.exit(1);
+}
+
+/**
+ * Runs one AI command in whichever mode is configured.
+ * @param {string} spinnerText  - shown while the request runs
+ * @param {string} successText  - shown when it completes
+ * @param {string} failText     - shown by the error handler on failure
+ * @param {Function} localFn    - BYOK path; returns the result object
+ * @param {string} endpoint     - hosted path, e.g. '/analyze'
+ * @param {Object} payload      - hosted path request body
+ * @returns result data object, or null on failure (already reported)
+ */
+async function runAICommand({ spinnerText, successText, failText, localFn, endpoint, payload }) {
+  let spinner;
+  try {
+    const byok = hasLocalKey();
+    const token = byok ? null : getToken();
+    if (!byok && !token) {
+      exitWithAuthGuidance();
+    }
+
+    spinner = ora(spinnerText).start();
+
+    const data = byok
+      ? await localFn()
+      : (await axios.post(apiEndpoint(endpoint), payload, {
+          headers: { Authorization: `Bearer ${token}` },
+        })).data;
+
+    spinner.succeed(successText);
+    return data;
+  } catch (err) {
+    handleCliError(spinner, err, failText);
+    return null;
+  }
+}
+
+export default runAICommand;

package/cli/utils/configManager.js

@@ -0,0 +1,144 @@
+// cli/utils/configManager.js
+// Single source of truth for all local CLI state: the config directory path,
+// config file read/write, auth token, OpenAI key (BYOK), and API URL.
+// (Previously split across getToken.js, apiConfig.js, and inline code in
+// loginHandlers.js — all reading the same file independently.)
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const CONFIG_DIR = path.join(os.homedir(), '.dev-toolkit');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+// One-time migration from the pre-rename config location (~/.dev-helper)
+const LEGACY_CONFIG_FILE = path.join(os.homedir(), '.dev-helper', 'config.json');
+if (!fs.existsSync(CONFIG_FILE) && fs.existsSync(LEGACY_CONFIG_FILE)) {
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs.copyFileSync(LEGACY_CONFIG_FILE, CONFIG_FILE);
+    fs.chmodSync(CONFIG_FILE, 0o600);
+  } catch {
+    // Migration is best-effort; a fresh config is created on next save
+  }
+}
+
+// There is no public hosted service — server mode requires a self-hosted
+// API, configured via the DEV_TOOLKIT_API_URL env var or `apiUrl` in the
+// config file.
+
+// Config holds secrets (token, OpenAI key) — owner read/write only.
+// Windows ignores POSIX modes; this is best-effort there.
+const SECRET_FILE_MODE = 0o600;
+
+function ensureConfigDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+}
+
+function getConfig() {
+  if (!fs.existsSync(CONFIG_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveConfig(config) {
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), {
+    encoding: 'utf-8',
+    mode: SECRET_FILE_MODE,
+  });
+}
+
+function setConfigValue(key, value) {
+  const config = getConfig();
+  config[key] = value;
+  saveConfig(config);
+}
+
+function removeConfigValue(key) {
+  const config = getConfig();
+  delete config[key];
+  saveConfig(config);
+}
+
+// ── Auth token (hosted-service mode) ────────────────────────────────────────
+
+function getToken() {
+  return getConfig().token || null;
+}
+
+function setToken(token) {
+  setConfigValue('token', token);
+}
+
+// ── OpenAI key (BYOK mode) ──────────────────────────────────────────────────
+
+function getOpenAIKey() {
+  // Environment variable takes precedence
+  if (process.env.OPENAI_API_KEY) {
+    return process.env.OPENAI_API_KEY;
+  }
+  // Fall back to config file
+  const config = getConfig();
+  return config.openaiApiKey || null;
+}
+
+function hasLocalKey() {
+  return !!getOpenAIKey();
+}
+
+function maskKey(key) {
+  if (!key || key.length < 8) return '****';
+  return key.slice(0, 7) + '...' + key.slice(-4);
+}
+
+// ── API URL (self-hosted server mode) ───────────────────────────────────────
+
+function getApiUrl() {
+  // Environment variable takes precedence
+  if (process.env.DEV_TOOLKIT_API_URL) {
+    return process.env.DEV_TOOLKIT_API_URL;
+  }
+  const config = getConfig();
+  if (config.apiUrl) {
+    return config.apiUrl;
+  }
+  return null;
+}
+
+function apiEndpoint(endpointPath) {
+  const apiUrl = getApiUrl();
+  if (!apiUrl) {
+    throw new Error(
+      'No API URL configured. Server mode requires a self-hosted Dev Toolkit server — ' +
+      'set DEV_TOOLKIT_API_URL or add "apiUrl" to your config. ' +
+      'Or skip the server entirely: devtk config set-key <your-openai-key>'
+    );
+  }
+  const baseUrl = apiUrl.replace(/\/$/, ''); // Remove trailing slash
+  return `${baseUrl}${endpointPath}`;
+}
+
+export {
+  CONFIG_DIR,
+  CONFIG_FILE,
+  SECRET_FILE_MODE,
+  getConfig,
+  saveConfig,
+  setConfigValue,
+  removeConfigValue,
+  getToken,
+  setToken,
+  getOpenAIKey,
+  hasLocalKey,
+  maskKey,
+  getApiUrl,
+  apiEndpoint,
+};

package/cli/utils/contextHandlerWrapper.js

@@ -0,0 +1,32 @@
+export default async function handleWithContext({ options, handleBasic, handleWithContext }) {
+  const {
+    file: filePath,
+    name: componentName,
+    description,
+    language = 'JavaScript',
+    fileType,
+    output,
+    outputPath,
+    goal,
+    context,      // boolean --context flag: include scanned project files
+    contextText,  // optional plain-text context string
+  } = options;
+
+  const sharedArgs = {
+    filePath,
+    componentName,
+    description,
+    language,
+    fileType,
+    output,
+    outputPath,
+    goal,
+    contextText,
+  };
+
+  if (context) {
+    await handleWithContext(sharedArgs);
+  } else {
+    await handleBasic(sharedArgs);
+  }
+};

package/cli/utils/errorHandler.js

@@ -0,0 +1,20 @@
+// utils/errorHandler.js
+import chalk from 'chalk';
+
+function handleCliError(spinner, err, fallbackMessage) {
+  if (spinner && spinner.isSpinning) spinner.fail(fallbackMessage);
+
+  if (err.response && err.response.data) {
+    // Only surface the server's intended error message — never dump the
+    // raw response body (it may contain internals we shouldn't echo).
+    const serverMsg = err.response.data.error || err.response.data.message
+      || `Request failed with status ${err.response.status}`;
+    console.error(chalk.red('❌ Server error:'), serverMsg);
+  } else if (err.message) {
+    console.error(chalk.red('❌ Error:'), err.message);
+  } else {
+    console.error(chalk.red('❌ Unknown failure occurred.'));
+  }
+}
+
+export default handleCliError;