@alhisan/gac 1.0.0

package/README.md

@@ -0,0 +1,144 @@
+# GPT4All CLI (gac)
+
+Terminal client for GPT4All running on localhost. Supports streaming responses, interactive chat, and configurable markdown rendering using `terminal-kit`.
+
+## Installation
+
+Requirements: Node.js 18+ and a running GPT4All OpenAI-compatible server.
+
+```bash
+npm install -g @alhisan/gac
+```
+
+Or if you don't want to install globally
+
+```bash
+npm install
+node bin/gac.js --help
+```
+
+Test if it works:
+
+```bash
+gac --help
+```
+
+## Usage
+
+Single prompt:
+
+```bash
+gac -a "Hello gpt4all, how are you doing today?"
+gac suggest "How do I connect to ssh server on a custom port 5322?"
+gac explain "How do I use rsync?"
+gac suggest -d "Give me step-by-step instructions to set up an SSH server on port 5322"
+```
+
+List models and set a default:
+
+```bash
+gac models
+```
+
+This opens an interactive selector. Use arrow keys + Enter to choose a model, or Ctrl+C/Esc to cancel.
+
+Interactive mode:
+
+```bash
+gac chat
+```
+
+Exit chat with `exit`, `quit`, or Ctrl+C.
+
+Flags:
+
+- `--no-render` disables markdown styling for that run.
+- `--debug-render` prints the raw model output after the rendered response.
+
+- `-d, --detailed-suggest` enable more detailed, step-by-step suggestions in `suggest` mode (can also be set via config key `detailedSuggest`).
+
+## Configuration
+
+Config file is created on first run:
+
+- Primary: `~/.gac/config.json`
+- Fallback: `.gac/config.json` (when home is not writable)
+
+View and edit:
+
+```bash
+gac config
+gac config get baseUrl
+gac config set baseUrl http://localhost:4891
+gac config set model "Llama 3 8B Instruct"
+gac config set markdownStyles.codeStyles '["#8be9fd"]'
+gac config set detailedSuggest true
+```
+
+### Core settings
+
+- `baseUrl` (string): GPT4All server base, e.g. `http://localhost:4891`
+- `model` (string): model ID from `/v1/models`
+- `temperature` (number)
+- `maxTokens` (number)
+- `stream` (boolean)
+- `detailedSuggest` (boolean): when `true`, `suggest` mode returns more detailed, step-by-step suggestions.
+- `renderMarkdown` (boolean)
+
+### Markdown styling
+
+All markdown options live under `markdownStyles`:
+
+- `headerStyles` (array of styles)
+- `headerStylesByLevel` (object, keys `1`–`6` → array of styles)
+- `headerUnderline` (boolean)
+- `headerUnderlineLevels` (array of levels to underline)
+- `headerUnderlineStyle` (array of styles)
+- `headerUnderlineChar` (string, single character)
+- `codeStyles` (array of styles)
+- `codeBackground` (array of styles)
+- `codeBorder` (boolean)
+- `codeBorderStyle` (array of styles)
+- `codeGutter` (string)
+- `codeBorderChars` (object: `topLeft`, `top`, `topRight`, `bottomLeft`, `bottom`, `bottomRight`)
+
+Style values can be:
+
+- Terminal-kit style names like `bold`, `underline`, `dim`, `brightWhite`
+- Foreground hex colors: `"#ffcc00"`
+- Background hex colors: `"bg:#202020"` or `"bg#202020"`
+- Default/transparent: `"default"` (fg) or `"bg:default"`
+
+Example:
+
+```json
+{
+  "markdownStyles": {
+    "headerStylesByLevel": {
+      "1": ["bold", "brightWhite"],
+      "2": ["bold"],
+      "3": ["bold"],
+      "4": ["dim"],
+      "5": ["dim"],
+      "6": ["dim"]
+    },
+    "headerUnderline": true,
+    "headerUnderlineLevels": [1],
+    "codeStyles": ["#8be9fd"],
+    "codeBackground": ["bg:default"],
+    "codeBorderStyle": ["#444444"]
+  }
+}
+```
+
+## Troubleshooting
+
+If you see connection errors, verify the server is reachable:
+
+```bash
+curl http://localhost:4891/v1/models
+```
+
+## License
+
+GNU General Public License v3.0. See `LICENSE`.

package/bin/gac.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import terminalKit from "terminal-kit";
+import { runCli } from "../src/cli.js";
+
+const { terminal: term } = terminalKit;
+
+runCli(process.argv).catch((err) => {
+  term(`Error: ${err.message}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@alhisan/gac",
+  "version": "1.0.0",
+  "description": "Terminal client for GPT4All running on localhost",
+  "license": "GPL-3.0-only",
+  "type": "module",
+  "bin": {
+    "gac": "bin/gac.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "terminal-kit": "^3.1.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,329 @@
+import terminalKit from "terminal-kit";
+import { chatCompletion, listModels } from "./gpt4all.js";
+import { getConfigPath, loadConfig, setConfigValue } from "./config.js";
+import { createMarkdownRenderer } from "./markdown.js";
+import os from "os";
+import process from "process";
+const { terminal: term } = terminalKit;
+
+function printHelp() {
+  term(`gac - GPT4All CLI\n\n`);
+  term(`Options:\n`);
+  term(`  -a                Single prompt mode (alias for ask)\n`);
+  term(`  suggest           Suggestion mode\n`);
+  term(`  explain           Explanation mode\n`);
+  term(`  ask               Ask mode\n`);
+  term(`  chat              Interactive chat mode\n`);
+  term(`  models            List models and set default\n`);
+  term(`  config            View or edit configuration\n`);
+  term(`  --no-render      Disable markdown rendering\n`);
+  term(`  --debug-render   Show both rendered and raw output\n`);
+  term(
+    `  -d, --detailed-suggest  Provide more detailed suggestions (only in suggest mode)\n`
+  );
+  term(`  -h, --help        Show this help message\n`);
+  term(`\n`);
+  term(`Usage:\n`);
+  term(`  gac -a "Hello gpt4all"\n`);
+  term(`  gac suggest "How do I connect to ssh server on port 5322"\n`);
+  term(`  gac explain "How do I use rsync?"\n`);
+  term(`  gac ask "What is the best way to learn JavaScript?"\n`);
+  term(`  gac chat\n`);
+  term(`  gac models\n`);
+  term(`  gac config\n`);
+  term(`  gac config get <key>\n`);
+  term(`  gac config set <key> <value>\n`);
+  term(`  gac --no-render -a "Raw markdown output"\n`);
+  term(`  gac --debug-render -a "Show rendered and raw output"\n`);
+  term(`\n`);
+}
+function getOSVersion() {
+  const platform = os.platform();
+  if (platform === "win32") {
+    // Which version of Windows?
+    if (process.env.OS_VERSION) {
+      return `${platform}: ${process.env.OS_VERSION}`;
+    } else if (process.env.OS_RELEASE) {
+      return `${platform}: ${process.env.OS_RELEASE}`;
+    } else if (process.env.OS) {
+      return `${platform}: ${process.env.OS}`;
+    } else {
+      return "Windows";
+    }
+  } else if (platform === "darwin") {
+    if (process.env.OS_VERSION) {
+      return `${platform}: ${process.env.OS_VERSION}`;
+    }
+    if (process.env.OS_RELEASE) {
+      return `${platform}: ${process.env.OS_RELEASE}`;
+    }
+    if (process.env.OS) {
+      return `${platform}: ${process.env.OS}`;
+    }
+    return "macOS";
+  }
+  if (platform === "linux") {
+    // Find which distro
+    if (process.env.OS_RELEASE) {
+      return `${platform}: ${process.env.OS_RELEASE}`;
+    } else if (process.env.OS) {
+      return `${platform}: ${process.env.OS}`;
+    } else if (process.env.LINUX_DISTRO) {
+      return `${platform}: ${process.env.LINUX_DISTRO}`;
+    }
+    return `Linux`;
+  }
+  if (platform === "freebsd") {
+    return "FreeBSD";
+  }
+  if (platform === "sunos") {
+    return "SunOS";
+  }
+  if (platform === "aix") {
+    return "AIX";
+  }
+  return "Unknown OS";
+}
+function buildSystemPrompt(mode, config) {
+  const osInfo = getOSVersion();
+
+  if (mode === "suggest") {
+    if (config.detailedSuggest === true) {
+      return `You are an expert technical assistant. The user is using a system with the following OS: ${osInfo}. When providing suggestions, give detailed, step-by-step instructions that the user can follow to achieve their goals. Include relevant commands, code snippets, or configurations as needed. Avoid unnecessary explanations or background information. Tailor your suggestions to be relevant to the user's operating system and environment.
+Attempt to make it a single line response where possible. Prefer commands and code snippets over lengthy explanations. Always leave commands and codes in their own line for easy copying.`;
+    } else {
+      return `You are an expert technical assistant. The user is using a system with the following OS: ${osInfo}. Provide concise and practical suggestions to help the user accomplish their tasks efficiently. Focus on clarity and brevity, ensuring that your suggestions are easy to understand and implement. Tailor your suggestions to be relevant to the user's operating system and environment. Avoid lengthy explanations or unnecessary details prefer single line commands or codes if you must include explainations make sure the commands and codes are in their own line for easy copying.`;
+    }
+  }
+  if (mode === "ask") {
+    return "Provide a helpful and accurate response to the user's question.";
+  }
+  if (mode === "explain") {
+    return "Explain step-by-step with a short example if helpful.";
+  }
+  return null;
+}
+
+async function runSinglePrompt(mode, prompt, config) {
+  const system = buildSystemPrompt(mode, config);
+  const messages = [];
+  if (system) messages.push({ role: "system", content: system });
+  messages.push({ role: "user", content: prompt });
+
+  const reply = await chatCompletion(config, messages);
+  if (!config.stream) {
+    if (config.renderMarkdown) {
+      const renderer = createMarkdownRenderer(config.markdownStyles);
+      term(`${renderer.renderText(reply)}\n`);
+    } else {
+      term(`${reply}\n`);
+    }
+  }
+  if (config.debugRender) {
+    term(`\n--- RAW ---\n${reply}\n`);
+  }
+  term(`\n`);
+}
+
+async function inputLine(label) {
+  term(label);
+  return new Promise((resolve) => {
+    term.inputField({ cancelable: true }, (error, input) => {
+      term("\n");
+      if (error || input === undefined || input === null) {
+        resolve("");
+        return;
+      }
+      resolve(input.trim());
+    });
+  });
+}
+
+async function runChat(config) {
+  term('Interactive chat. Type "exit" to quit.\n\n');
+  const messages = [];
+  term.grabInput({ mouse: "button" });
+  const cleanupChatInput = () => {
+    term.grabInput(false);
+    term.removeListener("key", onKey);
+  };
+  const onKey = (name) => {
+    if (name === "CTRL_C") {
+      cleanupChatInput();
+      term("\nBye.\n");
+      term.processExit(0);
+    }
+  };
+  term.on("key", onKey);
+
+  while (true) {
+    const prompt = await inputLine("You> ");
+    if (!prompt) continue;
+    if (prompt.toLowerCase() === "exit" || prompt.toLowerCase() === "quit") {
+      cleanupChatInput();
+      term("Bye.\n");
+      break;
+    }
+
+    messages.push({ role: "user", content: prompt });
+    term("A.I> ");
+    const reply = await chatCompletion(config, messages);
+    if (!config.stream) {
+      if (config.renderMarkdown) {
+        const renderer = createMarkdownRenderer(config.markdownStyles);
+        term(renderer.renderText(reply));
+      } else {
+        term(reply);
+      }
+    }
+    if (config.debugRender) {
+      term(`\n--- RAW ---\n${reply}\n`);
+    }
+    term("\n\n");
+    messages.push({ role: "assistant", content: reply });
+  }
+}
+
+async function runModels(config) {
+  let models;
+  try {
+    models = await listModels(config.baseUrl);
+  } catch (err) {
+    term(`Error: ${err.message}\n`);
+    term.processExit(1);
+  }
+
+  if (!models.length) {
+    term("No models found from GPT4All server.\n");
+    term.processExit(0);
+  }
+
+  term("Available models:\n");
+  // Append 'Use default gpt4all model' option at the top
+  models.unshift("Use default gpt4all setting");
+  models.forEach((model) => term(`- ${model}\n`));
+  term("\nSelect a default model (use arrows + Enter, Esc to cancel):\n");
+
+  const currentIndex = Math.max(models.indexOf(config.model), 0);
+  term.grabInput({ mouse: "button" });
+  const cleanup = () => {
+    term.grabInput(false);
+    term.removeListener("key", onKey);
+  };
+  const onKey = (name) => {
+    if (name === "CTRL_C") {
+      cleanup();
+      term("\nCanceled.\n");
+      term.processExit(0);
+    }
+  };
+  term.on("key", onKey);
+
+  await new Promise((resolve) => {
+    term.singleColumnMenu(
+      models,
+      { cancelable: true, selectedIndex: currentIndex },
+      (error, response) => {
+        term("\n");
+        if (error || !response || response.canceled) {
+          cleanup();
+          term("Selection canceled.\n");
+          term.processExit(0);
+        }
+        let selected = models[response.selectedIndex];
+        // if user selected the default model option, set to 'gpt4all'
+        if (selected === "Use default gpt4all setting") {
+          selected = "gpt4all";
+        }
+        setConfigValue("model", selected);
+        config.model = selected;
+        cleanup();
+        term(`Default model set to "${selected}".\n`);
+        term.processExit(0);
+      }
+    );
+  });
+}
+
+export async function runCli(argv) {
+  const args = argv.slice(2);
+  const config = loadConfig();
+  const noRenderIndex = args.indexOf("--no-render");
+  if (noRenderIndex !== -1) {
+    config.renderMarkdown = false;
+    args.splice(noRenderIndex, 1);
+  }
+  const debugRenderIndex = args.indexOf("--debug-render");
+  if (debugRenderIndex !== -1) {
+    config.debugRender = true;
+    args.splice(debugRenderIndex, 1);
+  }
+  const detailedSuggestIndex = args.indexOf("--detailed-suggest");
+  const shortDetailedSuggestIndex = args.indexOf("-d");
+
+  if (detailedSuggestIndex !== -1 || shortDetailedSuggestIndex !== -1) {
+    config.detailedSuggest = true;
+    if (detailedSuggestIndex !== -1) {
+      args.splice(detailedSuggestIndex, 1);
+    }
+    if (shortDetailedSuggestIndex !== -1) {
+      args.splice(shortDetailedSuggestIndex, 1);
+    }
+  }
+
+  if (args.length === 0 || args.includes("-h") || args.includes("--help")) {
+    printHelp();
+    return;
+  }
+
+  if (args[0] === "config") {
+    if (args[1] === "get" && args[2]) {
+      const key = args[2];
+      term(`${config[key]}\n`);
+      return;
+    }
+    if (args[1] === "set" && args[2] && args[3] !== undefined) {
+      const updated = setConfigValue(args[2], args.slice(3).join(" "));
+      term(`Updated ${args[2]} in ${getConfigPath()}\n`);
+      term(`${JSON.stringify(updated, null, 2)}\n`);
+      return;
+    }
+
+    term(`Config file: ${getConfigPath()}\n`);
+    term(`${JSON.stringify(config, null, 2)}\n`);
+    return;
+  }
+
+  if (args[0] === "chat") {
+    await runChat(config);
+    return;
+  }
+
+  if (args[0] === "models") {
+    await runModels(config);
+    return;
+  }
+
+  if (args[0] === "-a") {
+    const prompt = args.slice(1).join(" ").trim();
+    if (!prompt) {
+      term("Error: missing prompt after -a.\n");
+      term.processExit(1);
+    }
+    await runSinglePrompt("ask", prompt, config);
+    return;
+  }
+
+  if (args[0] === "suggest" || args[0] === "explain" || args[0] === "ask") {
+    const prompt = args.slice(1).join(" ").trim();
+    if (!prompt) {
+      term(`Error: missing prompt after ${args[0]}.\n`);
+      term.processExit(1);
+    }
+    await runSinglePrompt(args[0], prompt, config);
+    return;
+  }
+
+  term("Unknown command.\n\n");
+  printHelp();
+}

package/src/config.js

@@ -0,0 +1,129 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+const DEFAULT_CONFIG = {
+  baseUrl: "http://localhost:4891",
+  model: "gpt4all",
+  temperature: 0.7,
+  maxTokens: 512,
+  stream: true,
+  renderMarkdown: true,
+  debugRender: false,
+  detailedSuggest: false,
+  markdownStyles: {
+    headerStyles: ["bold"],
+    headerStylesByLevel: {
+      1: ["bold", "brightWhite"],
+      2: ["bold"],
+      3: ["bold"],
+      4: ["dim"],
+      5: ["dim"],
+      6: ["dim"],
+    },
+    headerUnderline: true,
+    headerUnderlineLevels: [1],
+    headerUnderlineStyle: ["dim"],
+    headerUnderlineChar: "─",
+    codeStyles: ["cyan"],
+    codeBackground: ["bgBlack"],
+    codeBorder: true,
+    codeBorderStyle: ["dim"],
+    codeGutter: "│ ",
+    codeBorderChars: {
+      topLeft: "┌",
+      top: "─",
+      topRight: "┐",
+      bottomLeft: "└",
+      bottom: "─",
+      bottomRight: "┘",
+    },
+  },
+};
+
+const HOME_CONFIG_DIR = path.join(os.homedir(), ".gac");
+const FALLBACK_CONFIG_DIR = path.join(process.cwd(), ".gac");
+let resolvedConfigDir = null;
+
+function resolveConfigDir() {
+  if (resolvedConfigDir) return resolvedConfigDir;
+
+  try {
+    fs.mkdirSync(HOME_CONFIG_DIR, { recursive: true });
+    resolvedConfigDir = HOME_CONFIG_DIR;
+    return resolvedConfigDir;
+  } catch (err) {
+    // Fall back to local config if home is not writable.
+  }
+
+  try {
+    fs.mkdirSync(FALLBACK_CONFIG_DIR, { recursive: true });
+    resolvedConfigDir = FALLBACK_CONFIG_DIR;
+    return resolvedConfigDir;
+  } catch (err) {
+    resolvedConfigDir = HOME_CONFIG_DIR;
+    return resolvedConfigDir;
+  }
+}
+
+export function getConfigPath() {
+  return path.join(resolveConfigDir(), "config.json");
+}
+
+export function loadConfig() {
+  const configPath = getConfigPath();
+  if (!fs.existsSync(configPath)) {
+    saveConfig(DEFAULT_CONFIG);
+    return { ...DEFAULT_CONFIG };
+  }
+
+  try {
+    const raw = fs.readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULT_CONFIG, ...parsed };
+  } catch (err) {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+export function saveConfig(config) {
+  const normalized = { ...DEFAULT_CONFIG, ...config };
+  const configPath = getConfigPath();
+  fs.writeFileSync(configPath, JSON.stringify(normalized, null, 2));
+}
+
+function coerceValue(value) {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+    (trimmed.startsWith("[") && trimmed.endsWith("]"))
+  ) {
+    try {
+      return JSON.parse(trimmed);
+    } catch (err) {
+      // Fall through to string handling.
+    }
+  }
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "null") return null;
+  if (!Number.isNaN(Number(trimmed)) && trimmed !== "") return Number(trimmed);
+  return value;
+}
+
+export function setConfigValue(key, value) {
+  const config = loadConfig();
+  const normalizedValue = coerceValue(value);
+  const parts = key.split(".");
+  let cursor = config;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const part = parts[i];
+    if (typeof cursor[part] !== "object" || cursor[part] === null) {
+      cursor[part] = {};
+    }
+    cursor = cursor[part];
+  }
+  cursor[parts[parts.length - 1]] = normalizedValue;
+  saveConfig(config);
+  return config;
+}