atlas-terminal 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Ispasou - Ispasa
+
+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,127 @@
+# ATLAS CLI 🤖
+
+A fast, lightweight AI assistant that lives in your terminal. Powered by Groq.
+
+![Version](https://img.shields.io/badge/version-1.0.0-blue?style=flat-square)
+![Node](https://img.shields.io/badge/node-18+-green?style=flat-square)
+![License](https://img.shields.io/badge/license-MIT-purple?style=flat-square)
+
+---
+
+## Installation
+
+```bash
+npm install -g atlas-cli
+```
+
+---
+
+## Quick Start
+
+### 1. Configure ATLAS with your Groq API key
+
+```bash
+atlas config
+```
+
+Get a free Groq API key at [console.groq.com](https://console.groq.com/keys)
+
+### 2. Start chatting
+
+```bash
+atlas chat
+```
+
+---
+
+## Commands
+
+### `atlas chat`
+Start a back and forth conversation with ATLAS. Conversation memory is maintained throughout the session.
+
+```bash
+atlas chat
+```
+
+```
+──────────────────────────────────────────────────
+  ATLAS — type your message, or "exit" to quit
+──────────────────────────────────────────────────
+
+You: what is a REST API?
+ATLAS: A REST API is...
+
+You: exit
+ATLAS: Goodbye!
+```
+
+---
+
+### `atlas ask`
+Ask a single question and get an answer immediately. Perfect for quick lookups without starting a full conversation.
+
+```bash
+atlas ask "what is the difference between null and undefined in JavaScript?"
+```
+
+Supports piping directly from the terminal:
+
+```bash
+cat error.log | atlas ask "what is wrong here?"
+echo "explain this code" | atlas ask --pipe < index.js
+```
+
+---
+
+### `atlas config`
+First time setup. Saves your Groq API key securely on your machine.
+
+```bash
+atlas config
+```
+
+Your API key is stored locally at `~/.config/atlas-cli/config.json` and never sent anywhere except directly to Groq.
+
+---
+
+## Requirements
+
+- Node.js 18 or higher
+- A free Groq API key from [console.groq.com](https://console.groq.com/keys)
+
+---
+
+## Tech Stack
+
+- **Node.js** — runtime
+- **Commander.js** — CLI command handling
+- **Groq SDK** — AI responses via llama-3.3-70b-versatile
+- **Chalk** — terminal colors
+- **Ora** — loading spinners
+- **Inquirer** — interactive config prompts
+- **Conf** — local config storage
+
+---
+
+## Roadmap
+
+- [x] `atlas chat` — conversational mode
+- [x] `atlas ask` — single question mode
+- [x] `atlas config` — API key setup
+- [ ] Streaming responses
+- [ ] `atlas chat` with file context (`atlas chat --file index.js`)
+- [ ] Web search tool
+- [ ] Read and write files
+- [ ] TTS voice mode
+- [ ] User accounts and hosted backend
+- [ ] Subscription tiers (Free / Pro / Ultimate)
+
+---
+
+## License
+
+MIT — feel free to use and modify.
+
+---
+
+Built by [Chris](https://github.com/PSGtatitos)

package/cli/commands/ask.js

@@ -0,0 +1,53 @@
+import chalk from 'chalk'
+import ora from 'ora'
+import { askGroq } from '../utils/groq.js'
+import Conf from 'conf'
+
+const config = new Conf({ projectName: 'atlas-cli' })
+
+export async function askCommand(question) {
+  // Check config exists
+  if (!config.get('groqApiKey')) {
+    console.log(chalk.red('No API key found. Run atlas config first.'))
+    process.exit(1)
+  }
+
+  // Handle piped input
+  if (!question) {
+    const chunks = []
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk)
+    }
+    question = Buffer.concat(chunks).toString().trim()
+  }
+
+  if (!question) {
+    console.log(chalk.red('No question provided.'))
+    process.exit(1)
+  }
+
+  const spinner = ora('Thinking...').start()
+
+  try {
+    spinner.stop()
+    process.stdout.write(chalk.blue('ATLAS: '))
+
+    const stream = await askGroq(question, [])
+
+    for await (const chunk of stream) {
+      const token = chunk.choices[0]?.delta?.content || ''
+      process.stdout.write(token)
+    }
+
+    console.log('\n')
+
+  } catch (error) {
+    spinner.stop()
+    if (error.message?.includes('API key')) {
+      console.log(chalk.red('Invalid API key. Run atlas config to update it.'))
+    } else {
+      console.log(chalk.red(`Error: ${error.message}`))
+    }
+    process.exit(1)
+  }
+}

package/cli/commands/chat.js

@@ -0,0 +1,109 @@
+import readline from 'readline'
+import chalk from 'chalk'
+import { askGroq } from '../utils/groq.js'
+import { handleSystemCommand } from '../utils/system.js'
+import Conf from 'conf'
+
+const config = new Conf({ projectName: 'atlas-cli' })
+
+const STOP_PHRASES = [
+  'goodbye atlas',
+  'goodbye',
+  'exit',
+  'quit',
+  'ok that is all for today',
+  "that's all for today",
+  "ok that's all"
+]
+
+const NOISE_WORDS = new Set([
+  '', 'huh', 'uh', 'um', 'hmm',
+  'ah', 'oh', 'eh', 'a', 'the', 'i', 'it'
+])
+
+const MIN_INPUT_LENGTH = 2
+
+export async function chatCommand() {
+  // Check config exists
+  if (!config.get('groqApiKey')) {
+    console.log(chalk.red('No API key found. Run atlas config first.'))
+    process.exit(1)
+  }
+
+  const conversationHistory = []
+
+  console.log(chalk.cyan('─'.repeat(50)))
+  console.log(chalk.cyan('  ATLAS — type your message, or "exit" to quit'))
+  console.log(chalk.cyan('─'.repeat(50)) + '\n')
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  })
+
+  const askQuestion = () => {
+    rl.question(chalk.green('You: '), async (input) => {
+      const userInput = input.trim()
+
+      // Empty input
+      if (!userInput) {
+        return askQuestion()
+      }
+
+      // Stop phrases
+      if (STOP_PHRASES.some(p => userInput.toLowerCase().includes(p))) {
+        console.log(chalk.cyan('\nATLAS: Goodbye!\n'))
+        rl.close()
+        return
+      }
+
+      // Noise/short input
+      if (
+        userInput.length < MIN_INPUT_LENGTH ||
+        NOISE_WORDS.has(userInput.toLowerCase())
+      ) {
+        console.log(chalk.gray('[Skipped] Input too short.\n'))
+        return askQuestion()
+      }
+
+      // System command check
+      const systemResponse = handleSystemCommand(userInput)
+      if (systemResponse) {
+        console.log(chalk.yellow(`System: ${systemResponse}\n`))
+        return askQuestion()
+      }
+
+      // Ask Groq
+      try {
+        process.stdout.write(chalk.blue('ATLAS: '))
+
+        const stream = await askGroq(userInput, conversationHistory)
+
+        let fullResponse = ''
+
+        for await (const chunk of stream) {
+          const token = chunk.choices[0]?.delta?.content || ''
+          process.stdout.write(token)
+          fullResponse += token
+        }
+
+        console.log('\n')
+
+        // Update conversation history
+        conversationHistory.push({ role: 'user', content: userInput })
+        conversationHistory.push({ role: 'assistant', content: fullResponse })
+
+      } catch (error) {
+        if (error.message?.includes('API key')) {
+          console.log(chalk.red('\nInvalid API key. Run atlas config to update it.\n'))
+        } else {
+          console.log(chalk.red(`\nError: ${error.message}\n`))
+        }
+      }
+
+      askQuestion()
+    })
+  }
+
+  askQuestion()
+}

package/cli/commands/config.js

@@ -0,0 +1,47 @@
+import inquirer from 'inquirer'
+import chalk from 'chalk'
+import Conf from 'conf'
+import Groq from 'groq-sdk'
+
+const config = new Conf({ projectName: 'atlas-cli' })
+
+export async function configCommand() {
+  console.log(chalk.cyan('\nWelcome to ATLAS setup!\n'))
+
+  const existing = config.get('groqApiKey')
+  if (existing) {
+    console.log(chalk.gray(`Current API key: ${existing.slice(0, 8)}...\n`))
+  }
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'password',
+      name: 'groqApiKey',
+      message: 'Enter your Groq API key (get one at console.groq.com):',
+      mask: '*',
+      validate: (val) => val.length > 0 ? true : 'API key cannot be empty'
+    }
+  ])
+
+  // Validate the key by making a test call
+  console.log(chalk.gray('\nValidating API key...'))
+
+  try {
+    const groq = new Groq({ apiKey: answers.groqApiKey })
+    await groq.chat.completions.create({
+      model: 'llama-3.3-70b-versatile',
+      messages: [{ role: 'user', content: 'hi' }],
+      max_tokens: 1
+    })
+
+    config.set('groqApiKey', answers.groqApiKey)
+
+    console.log(chalk.green('\n✓ API key valid'))
+    console.log(chalk.green('✓ ATLAS is ready'))
+    console.log(chalk.cyan('\nRun atlas chat to start.\n'))
+
+  } catch (error) {
+    console.log(chalk.red('\n✗ Invalid API key. Please check and try again.\n'))
+    process.exit(1)
+  }
+}

package/cli/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { program } from 'commander'
+import { chatCommand } from './commands/chat.js'
+import { askCommand } from './commands/ask.js'
+import { configCommand } from './commands/config.js'
+
+program
+  .name('atlas')
+  .description('AI assistant that lives in your terminal')
+  .version('1.0.0')
+
+program
+  .command('chat')
+  .description('Start a conversation with ATLAS')
+  .action(chatCommand)
+
+program
+  .command('ask <question>')
+  .description('Ask ATLAS a single question')
+  .action(askCommand)
+
+program
+  .command('config')
+  .description('Configure ATLAS settings')
+  .action(configCommand)
+
+program.parse()

package/cli/utils/groq.js

@@ -0,0 +1,26 @@
+// groq.js
+import Groq from 'groq-sdk'
+import Conf from 'conf'
+
+const config = new Conf({ projectName: 'atlas-cli' })
+
+export async function askGroq(text, conversationHistory) {
+  const groq = new Groq({ 
+    apiKey: config.get('groqApiKey') 
+  })
+
+  const response = await groq.chat.completions.create({
+    model: 'llama-3.3-70b-versatile',
+    messages: [
+      {
+        role: 'system',
+        content: 'You are ATLAS, an AI assistant in the terminal.'
+      },
+      ...conversationHistory,
+      { role: 'user', content: text }
+    ],
+    stream: true  // streaming so responses print token by token
+  })
+
+  return response
+}

package/cli/utils/system.js

@@ -0,0 +1,32 @@
+export function handleSystemCommand(text) {
+  const t = text.toLowerCase()
+
+  const commonSites = {
+    youtube:   'https://youtube.com',
+    google:    'https://google.com',
+    netflix:   'https://netflix.com',
+    github:    'https://github.com',
+    reddit:    'https://reddit.com',
+    twitter:   'https://twitter.com',
+    instagram: 'https://instagram.com',
+    gmail:     'https://gmail.com',
+  }
+
+  // Common site shortcuts
+  for (const [name, url] of Object.entries(commonSites)) {
+    if (t.includes(`open ${name}`)) {
+      // Will be handled by agent tool in Phase 2
+      return `Would open ${url} (system commands coming in v2)`
+    }
+  }
+
+  // Search
+  if (t.includes('search for') || t.includes('google search')) {
+    const query = t.includes('search for')
+      ? t.split('search for')[1].trim()
+      : t.split('google search')[1].trim()
+    return `Would search for "${query}" (system commands coming in v2)`
+  }
+
+  return null
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "atlas-terminal",
+  "version": "1.0.0",
+  "description": "AI assistant that lives in your terminal",
+  "main": "cli/index.js",
+  "bin": {
+    "atlas": "./cli/index.js"
+  },
+  "files": [
+    "cli/"
+  ],
+  "type": "module",
+  "scripts": {
+    "start": "node cli/index.js",
+    "dev": "node --watch cli/index.js"
+  },
+  "keywords": ["ai", "cli", "assistant", "terminal"],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.0",
+    "inquirer": "^9.0.0",
+    "conf": "^12.0.0",
+    "groq-sdk": "^0.3.0"
+  }
+}