@theonlykaks/kaks 0.0.1

package/.env.example

@@ -0,0 +1,2 @@
+GEMINI_API_KEY=your_own_gemini_api_key
+OPENAI_API_KEY=your_own_openai_api_key

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arush Khasru
+
+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/cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import 'dotenv/config';
+import process from 'node:process';
+
+import { Command } from 'commander';
+
+import { registerAskCommand } from './src/commands/ask.js';
+import { registerConfigCommand } from './src/commands/config.js';
+import { registerExplainCommand } from './src/commands/explain.js';
+import { registerGoCommand } from './src/commands/go.js';
+import { registerInitCommand } from './src/commands/init.js';
+import { registerOpenCommand } from './src/commands/open.js';
+import { registerStartCommand } from './src/commands/start.js';
+import { registerSummarizeCommand } from './src/commands/summarize.js';
+import { CONFIG_PATH, pathExists } from './src/commands/shared.js';
+
+const program = new Command();
+
+program
+  .name('kaks')
+  .description('AI-powered developer assistant and workspace launcher')
+  .version('0.0.1')
+  .showHelpAfterError()
+  .showSuggestionAfterError()
+  .addHelpText('after', `
+
+Examples:
+  $ kaks init
+  $ kaks ask "How do I read a file async in Node.js?"
+  $ kaks explain package.json
+  $ kaks summarize app.log --tail 200
+  $ kaks open myapp
+  $ kaks start myapp
+  $ kaks go github.com
+`);
+
+registerAskCommand(program);
+registerExplainCommand(program);
+registerSummarizeCommand(program);
+registerOpenCommand(program);
+registerStartCommand(program);
+registerGoCommand(program);
+registerConfigCommand(program);
+registerInitCommand(program);
+
+if (process.argv.length <= 2) {
+  if (!(await pathExists(CONFIG_PATH))) {
+    console.log('Welcome to kaks-cli.');
+    console.log('It looks like this is your first time. Run: kaks init\n');
+  }
+
+  program.outputHelp();
+} else {
+  await program.parseAsync(process.argv);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@theonlykaks/kaks",
+  "version": "0.0.1",
+  "description": "Hello_to_the_cli",
+  "keywords": [],
+  "homepage": "https://github.com/ArushKhasru/kaks#readme",
+  "bugs": {
+    "url": "https://github.com/ArushKhasru/kaks/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArushKhasru/kaks.git"
+  },
+  "license": "ISC",
+  "author": "kaks",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "kaks": "cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "axios": "^1.16.1",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "dotenv": "^17.4.2",
+    "execa": "^9.6.1",
+    "inquirer": "^13.4.3",
+    "nodemon": "^3.1.14",
+    "ora": "^9.4.0"
+  }
+}

package/readme.md

@@ -0,0 +1,88 @@
+# kaks CLI
+
+AI-powered developer assistant and workspace launcher for Windows-first workflows.
+
+**Status:** Work in progress. Core commands are implemented and usable.
+
+## What works today
+- `kaks init` interactive setup for provider, model, editor, and optional project registration
+- `kaks ask` AI Q&A with optional clipboard copy
+- `kaks explain` AI file explanations with detail/section controls
+- `kaks summarize` log summarization with local JSON summary and optional AI insight
+- `kaks open` open project editor, browser URLs, and file explorer
+- `kaks start` run configured services concurrently (attached or detached)
+- `kaks go` normalize/open/copy/print URLs quickly
+- `kaks config` set/get/list/add-project/remove-project/edit global config
+
+## Install (local dev)
+```bash
+git clone https://github.com/ArushKhasru/Kaks.git
+cd kaks
+npm install
+npm link
+```
+
+Then run:
+```bash
+kaks --help
+```
+
+You can also run directly:
+```bash
+node cli.js --help
+```
+
+## Quick start
+```bash
+kaks init
+kaks ask "How do I read a file async in Node.js?"
+kaks explain package.json
+kaks summarize app.log --tail 200
+kaks open myapp
+kaks start myapp
+kaks go github.com
+```
+
+## Configuration
+Global config is stored at `~/.kaks/config.json`. Project-local config is `.kaks.json`.
+
+Environment variables:
+- `GEMINI_API_KEY`
+- `OPENAI_API_KEY`
+
+`kaks init` can also write the key into a local `.env` file.
+
+Example config:
+```jsonc
+{
+  "ai": {
+    "provider": "gemini",
+    "model": "gemini-2.0-flash",
+    "temperature": 0.7,
+    "maxTokens": 2048
+  },
+  "projects": {
+    "myapp": {
+      "path": "D:\\projects\\myapp",
+      "browser": "http://localhost:3000",
+      "editor": "code",
+      "services": [
+        { "name": "frontend", "cmd": "npm run dev", "cwd": "./client", "port": 3000 },
+        { "name": "backend", "cmd": "npm run dev", "cwd": "./server", "port": 5000 }
+      ]
+    }
+  },
+  "defaults": {
+    "editor": "code",
+    "browser": "default",
+    "shell": "powershell"
+  }
+}
+```
+
+`kaks ask` reads `ai.context` from `.kaks.json` to enrich prompts.
+
+## AI providers
+- **Gemini**: uses `GEMINI_API_KEY`
+- **OpenAI**: uses `OPENAI_API_KEY`
+- **Ollama**: uses `http://localhost:11434` with no API key

package/src/commands/ask.js

@@ -0,0 +1,81 @@
+import inquirer from 'inquirer';
+
+import {
+  completeWithAi,
+  copyToClipboard,
+  handleCommandError,
+  loadGlobalConfig,
+  loadLocalConfig,
+  runWithSpinner,
+} from './shared.js';
+
+const SYSTEM_PROMPT = [
+  'You are a senior developer assistant.',
+  'Answer concisely, use markdown when helpful, and include code examples for coding questions.',
+  'Prefer practical, directly usable guidance.',
+].join(' ');
+
+export function registerAskCommand(program) {
+  program
+    .command('ask [question...]')
+    .description('Ask an AI-powered developer question')
+    .option('--model <model>', 'Override the configured model')
+    .option('--no-stream', 'Disable streaming output')
+    .option('--copy', 'Copy the answer to the clipboard')
+    .addHelpText('after', `
+
+Examples:
+  $ kaks ask "How do I read a file async in Node.js?"
+  $ kaks ask --model gpt-4o-mini "Explain Promise.allSettled"
+`)
+    .action(async (questionParts = [], options) => {
+      try {
+        await ask(questionParts, options);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}
+
+export async function ask(questionParts = [], options = {}) {
+  const question = await resolveQuestion(questionParts);
+  const config = await loadGlobalConfig();
+  const localConfig = await loadLocalConfig();
+
+  const context = localConfig?.ai?.context
+    ? `\n\nProject context:\n${localConfig.ai.context}`
+    : '';
+
+  const answer = await runWithSpinner('Reading...', () => completeWithAi({
+    systemPrompt: SYSTEM_PROMPT,
+    userPrompt: `${question}${context}`,
+    config,
+    model: options.model,
+  }));
+
+  console.log(`\n${answer}\n`);
+
+  if (options.copy) {
+    await copyToClipboard(answer);
+    console.log('Copied answer to clipboard.');
+  }
+}
+
+async function resolveQuestion(questionParts) {
+  const question = Array.isArray(questionParts) ? questionParts.join(' ').trim() : String(questionParts ?? '').trim();
+
+  if (question) {
+    return question;
+  }
+
+  const answer = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'question',
+      message: 'Question',
+      validate: (value) => Boolean(value.trim()) || 'Enter a question.',
+    },
+  ]);
+
+  return answer.question.trim();
+}

package/src/commands/config.js

@@ -0,0 +1,213 @@
+import path from 'node:path';
+import process from 'node:process';
+
+import inquirer from 'inquirer';
+
+import {
+  CONFIG_PATH,
+  CliError,
+  deleteByPath,
+  getByPath,
+  handleCommandError,
+  launchEditor,
+  loadGlobalConfig,
+  parseConfigValue,
+  resolveUserPath,
+  saveGlobalConfig,
+  setByPath,
+  validateConfigValue,
+} from './shared.js';
+
+export function registerConfigCommand(program) {
+  const configCommand = program
+    .command('config')
+    .description('Manage global kaks configuration');
+
+  configCommand
+    .command('set <key> <value>')
+    .description('Set a config value using dot notation')
+    .action(async (key, rawValue) => {
+      try {
+        await setConfig(key, rawValue);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  configCommand
+    .command('get <key>')
+    .description('Read a config value using dot notation')
+    .action(async (key) => {
+      try {
+        await getConfig(key);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  configCommand
+    .command('list')
+    .description('Print the full global configuration')
+    .action(async () => {
+      try {
+        await listConfig();
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  configCommand
+    .command('add-project <name>')
+    .description('Register a project preset')
+    .option('--path <path>', 'Project root path')
+    .option('--browser <url>', 'Default URL to open for this project')
+    .option('--editor <editor>', 'Editor command for this project')
+    .action(async (name, options) => {
+      try {
+        await addProject(name, options);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  configCommand
+    .command('remove-project <name>')
+    .description('Remove a project preset')
+    .option('--yes', 'Skip confirmation')
+    .action(async (name, options) => {
+      try {
+        await removeProject(name, options);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  configCommand
+    .command('edit')
+    .description('Open the global config file in your editor')
+    .action(async () => {
+      try {
+        await editConfig();
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}
+
+export async function setConfig(key, rawValue) {
+  const value = parseConfigValue(rawValue);
+  validateConfigValue(key, value);
+
+  const config = await loadGlobalConfig();
+  setByPath(config, key, value);
+  await saveGlobalConfig(config);
+  console.log(`Set ${key}.`);
+}
+
+export async function getConfig(key) {
+  const config = await loadGlobalConfig();
+  const value = getByPath(config, key);
+
+  if (value === undefined) {
+    throw new CliError(`Config key not found: ${key}`);
+  }
+
+  console.log(typeof value === 'object' ? JSON.stringify(value, null, 2) : String(value));
+}
+
+export async function listConfig() {
+  const config = await loadGlobalConfig();
+  console.log(JSON.stringify(config, null, 2));
+}
+
+export async function addProject(name, options = {}) {
+  const config = await loadGlobalConfig();
+  const answers = await promptForMissingProjectFields(name, options);
+  const projectPath = resolveUserPath(answers.path);
+
+  config.projects ??= {};
+  config.projects[name] = {
+    path: projectPath,
+    browser: answers.browser || undefined,
+    editor: answers.editor || undefined,
+  };
+
+  await saveGlobalConfig(config);
+  console.log(`Added project "${name}" -> ${projectPath}`);
+}
+
+export async function removeProject(name, options = {}) {
+  const config = await loadGlobalConfig();
+
+  if (!config.projects?.[name]) {
+    throw new CliError(`Project not found: ${name}`);
+  }
+
+  if (!options.yes) {
+    const { confirmed } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirmed',
+        message: `Remove project "${name}"?`,
+        default: false,
+      },
+    ]);
+
+    if (!confirmed) {
+      console.log('Canceled.');
+      return;
+    }
+  }
+
+  deleteByPath(config, `projects.${name}`);
+  await saveGlobalConfig(config);
+  console.log(`Removed project "${name}".`);
+}
+
+export async function editConfig() {
+  const config = await loadGlobalConfig();
+  await saveGlobalConfig(config);
+  await launchEditor(config.defaults?.editor ?? 'code', CONFIG_PATH);
+  console.log(`Opening ${CONFIG_PATH}`);
+}
+
+async function promptForMissingProjectFields(name, options) {
+  const questions = [];
+
+  if (!options.path) {
+    questions.push({
+      type: 'input',
+      name: 'path',
+      message: `Path for ${name}`,
+      default: process.cwd(),
+      filter: (value) => path.resolve(value),
+      validate: (value) => Boolean(value.trim()) || 'Enter a project path.',
+    });
+  }
+
+  if (!options.browser) {
+    questions.push({
+      type: 'input',
+      name: 'browser',
+      message: 'Default browser URL',
+      default: '',
+    });
+  }
+
+  if (!options.editor) {
+    questions.push({
+      type: 'input',
+      name: 'editor',
+      message: 'Editor command',
+      default: '',
+    });
+  }
+
+  const answers = questions.length ? await inquirer.prompt(questions) : {};
+
+  return {
+    path: options.path ?? answers.path,
+    browser: options.browser ?? answers.browser,
+    editor: options.editor ?? answers.editor,
+  };
+}

package/src/commands/explain.js

@@ -0,0 +1,79 @@
+import { CliError, completeWithAi, detectLanguage, handleCommandError, loadGlobalConfig, readTextFileWithLimits, runWithSpinner } from './shared.js';
+
+const SYSTEM_PROMPT = [
+  'You are a code and configuration file explainer.',
+  'Explain the file in plain English for a developer.',
+  'Cover purpose, structure, important sections, and any risks or noteworthy details.',
+].join(' ');
+
+const VALID_DETAIL_LEVELS = new Set(['low', 'medium', 'high']);
+
+export function registerExplainCommand(program) {
+  program
+    .command('explain <filepath>')
+    .description('Explain a source, config, or text file with AI')
+    .option('--detail <level>', 'Depth of explanation: low, medium, or high', 'medium')
+    .option('--section <name>', 'Explain only a named section or topic')
+    .option('--model <model>', 'Override the configured model')
+    .addHelpText('after', `
+
+Examples:
+  $ kaks explain docker-compose.yml
+  $ kaks explain package.json --detail high
+  $ kaks explain src/app.js --section middleware
+`)
+    .action(async (filepath, options) => {
+      try {
+        await explain(filepath, options);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}
+
+export async function explain(filepath, options = {}) {
+  const detail = String(options.detail ?? 'medium').toLowerCase();
+  if (!VALID_DETAIL_LEVELS.has(detail)) {
+    throw new CliError('Invalid detail level. Use one of: low, medium, high.');
+  }
+
+  const file = await readTextFileWithLimits(filepath);
+
+  if (!file.content.trim()) {
+    throw new CliError(`File is empty: ${filepath}`);
+  }
+
+  if (file.warned) {
+    console.warn(`Large file: ${file.displayPath} (${file.size} bytes).`);
+  }
+
+  if (file.truncated) {
+    console.warn('File exceeds 500KB, so only the first 500KB will be explained.');
+  }
+
+  const config = await loadGlobalConfig();
+  const language = detectLanguage(file.absolutePath);
+  const section = options.section ? `\nFocus only on this section or topic: ${options.section}` : '';
+
+  const prompt = [
+    `File: ${file.displayPath}`,
+    `Detected format: ${language}`,
+    `Detail level: ${detail}`,
+    section,
+    '',
+    'Content:',
+    `\`\`\`${language}`,
+    file.content,
+    '```',
+  ].filter(Boolean).join('\n');
+
+  const explanation = await runWithSpinner(`Reading ${file.displayPath}...`, () => completeWithAi({
+    systemPrompt: SYSTEM_PROMPT,
+    userPrompt: prompt,
+    config,
+    model: options.model,
+  }));
+
+  console.log(`\nFile Explanation: ${file.displayPath}\n`);
+  console.log(`${explanation}\n`);
+}

package/src/commands/go.js

@@ -0,0 +1,51 @@
+import {
+  assertValidUrl,
+  copyToClipboard,
+  handleCommandError,
+  normalizeUrl,
+  openTarget,
+} from './shared.js';
+
+export function registerGoCommand(program) {
+  program
+    .command('go <url>')
+    .description('Normalize and open a URL quickly')
+    .option('--browser <name>', 'Browser override: chrome, firefox, edge, or default', 'default')
+    .option('--copy', 'Copy the normalized URL instead of opening it')
+    .option('--print', 'Print the normalized URL instead of opening it')
+    .addHelpText('after', `
+
+Examples:
+  $ kaks go github.com
+  $ kaks go github.com/kaksKhasru/kaks
+  $ kaks go localhost:3000
+  $ kaks go docs.google.com --copy
+`)
+    .action(async (url, options) => {
+      try {
+        await go(url, options);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}
+
+export async function go(url, options = {}) {
+  const normalizedUrl = normalizeUrl(url);
+  assertValidUrl(normalizedUrl);
+
+  if (options.print) {
+    console.log(normalizedUrl);
+    return;
+  }
+
+  if (options.copy) {
+    await copyToClipboard(normalizedUrl);
+    console.log(`Copied to clipboard: ${normalizedUrl}`);
+    return;
+  }
+
+  await openTarget(normalizedUrl, options.browser);
+  const suffix = options.browser && options.browser !== 'default' ? ` (${options.browser})` : '';
+  console.log(`Opening ${normalizedUrl}${suffix}`);
+}